standard_id-provider 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9592cd119ffb18ff4e2cf19a9feaca0058aee05edfe5ab24a01f18fbd3c4b1b
-  data.tar.gz: dc8fce05e463d51f56bfe482e7589ab274a183b58fa914ceca08fa53ebdbce42
+  metadata.gz: f96f308e0b1b4b60787511200833a782631a6e1934a2f53b421172651c0b6d84
+  data.tar.gz: 1fc3b9bb28515cabeee83feb4c796f16fa77313fbee2977ac309ac1759955c85
 SHA512:
-  metadata.gz: f6c57e6ee827fb92f2a48266c01579a272fb5b8c6605da5ed6c078d3aeb796ad4e6dfb2ebb501c75eb99239426628019f26f80aed085dc536794829e3854e86e
-  data.tar.gz: 1d3eb26ad72aa0b2c4958771f2f008355329213eb4863ab9a03cbecf5807f3e230eef1382813da5d68c6a39e287ac90f8c358a63e22978db1a008e341ed96f94
+  metadata.gz: 1246b085ad43df34f775c8c953123cc2e4bb00e0327591d5b7f18bfed36cc43da6fd468e7b96677f499433e4841f0634ade7eff44f98fed59700e0cfa5e97e5b
+  data.tar.gz: 72391d0a9c8b01c9f2b50b53f0c5582dede2987cec347d0451f26d2086944b228fcaa408b482f23539a71968e5f408ff8901ae06561daa31236587aa8692ca91

data/README.md

@@ -1,28 +1,202 @@
 # StandardId::Provider
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+OpenID Connect Identity Provider addon for [`standard_id`](https://github.com/rarebit-one/standard_id).
+
+`standard_id` gives you OAuth 2.0 — authorization codes, token exchange, refresh
+tokens, sessions. This engine adds the parts that make it an **OpenID Connect
+identity provider**:
+
+| | |
+|---|---|
+| **ID tokens** | Signed OIDC ID tokens issued alongside access tokens, with `nonce`, `auth_time`, `at_hash` and `c_hash` |
+| **Consent** | Per-`(account, client)` scope grants, checked on subsequent authorization requests |
+| **Access-token revocation** | An RFC 7009 endpoint backed by a `jti` denylist — the thing that makes revoking a *stateless* access token actually bite |
+| **Discovery** | `/.well-known/openid-configuration`, built from core's document builder so it cannot drift |
+
+## Read this before adopting it
+
+**This engine `prepend`s into non-public `standard_id` internals.** That is not
+an implementation detail you can ignore — it is the coupling you are taking on.
+
+It prepends into five classes, none of which are part of `standard_id`'s public
+API and none of which carry a stability guarantee:
+
+| Class | Why |
+|---|---|
+| `StandardId::Oauth::TokenGrantFlow` | issue an ID token with the access token; stamp `jti` |
+| `StandardId::Oauth::AuthorizationCodeAuthorizationFlow` | carry `nonce` / consent through authorization |
+| `StandardId::Oauth::Subflows::TraditionalCodeGrant` | ditto, for the traditional code grant |
+| `StandardId::Oauth::AuthorizationCodeFlow` | ditto |
+| `StandardId::Api::Oauth::IntrospectionsController` | contribute the revocation denylist into core's RFC 7662 endpoint (a **private** method) |
+
+What that means in practice:
+
+* **A `standard_id` minor release can break this gem** without breaking its own
+  semver contract, because the coupling is to internals rather than API.
+* The gemspec therefore pins `standard_id` to `~> 0.33` — the oldest version
+  this gem's suite has actually been run against.
+* A **`compat` CI job** resolves against the latest *published* `standard_id`
+  and runs the full suite against it on every push, so a break surfaces here
+  before it surfaces in your app.
+
+If you want OIDC without that coupling, you want `standard_id` on its own plus
+your own ID-token issuance. If you want the coupling handled for you, this is
+the gem.
 
 ## Installation
-Add this line to your application's Gemfile:
 
 ```ruby
+# Gemfile
 gem "standard_id-provider"
 ```
 
-And then execute:
 ```bash
-$ bundle
+bundle install
+rails generate standard_id:provider:install
+rails db:migrate
+```
+
+The generator:
+
+* copies the engine's migrations (`consent_grants`, `revoked_tokens`) into
+  `db/migrate/`
+* writes `config/initializers/standard_id_provider.rb`
+* mounts the engine in `config/routes.rb`
+
+It is **idempotent** — re-running skips anything already installed and says so.
+
+| Flag | Effect |
+|---|---|
+| `--skip-migrations` | leave `db/migrate/` alone |
+| `--skip-initializer` | do not write the initializer |
+| `--skip-routes` | do not touch `config/routes.rb` |
+| `--mount-path PATH` | mount somewhere other than `/` |
+| `--force` | overwrite an existing initializer |
+
+## Mounting
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  mount StandardId::Provider::Engine => "/"
+  mount StandardId::WebEngine => "/", as: :standard_id_web
+
+  scope "api" do
+    mount StandardId::ApiEngine => "/", as: :standard_id_api
+  end
+end
 ```
 
-Or install it yourself as:
+The engine serves, relative to its own mount:
+
+| Route | What |
+|---|---|
+| `GET /.well-known/openid-configuration` | OIDC discovery document |
+| `POST /api/provider/revoke` | RFC 7009 revocation — writes the `jti` denylist |
+| `GET\|POST\|DELETE /api/provider/consent` | consent grant management |
+
+Introspection is **not** here — see below.
+
+## Configuration
+
+The generator writes a fully commented initializer. Two settings are load-bearing
+and easy to miss.
+
+### `discovery_endpoint_base` — required
+
+```ruby
+StandardId.configure do |c|
+  c.issuer = "https://auth.example.com"
+  c.oauth.discovery_endpoint_base = ->(request:) { "#{request.base_url}/api" }
+end
+```
+
+The **issuer** and the **endpoint base** are different things. The issuer is a
+stable security identifier (RFC 8414 §2) that clients match byte-for-byte
+against their discovery URL and against the `iss` claim of issued tokens. The
+endpoint base is merely where the endpoints live.
+
+This engine's discovery document is served from the *Provider* engine's mount.
+Core's own well-known controllers sit inside the `ApiEngine` mount and can read
+it out of `SCRIPT_NAME`; this one cannot. If you do not name the base, the
+document will advertise URLs that 404.
+
+Use `discovery_metadata_overrides` for members that cannot be derived — a
+host-owned authorization shim, a deliberately narrower scope list. They are
+applied last and win over everything else. Setting `issuer` there raises.
+
+### `introspection_enabled` — opt-in, and it is core's endpoint
+
+```ruby
+c.oauth.introspection_enabled = true
+```
+
+RFC 7662 introspection is **core's** endpoint (`POST /oauth/introspect`), not
+this engine's. It is off by default and 404s until you opt in.
+
+This engine used to ship a second one. It no longer does, because core's is
+strictly more conformant — RFC 7662 §2.2 requires every failure mode to render
+`{"active": false}` and nothing else, and this gem's answered `401` on bad
+client credentials and `429` when throttled, which let a caller distinguish
+"your credentials are wrong" and "you are throttled" from "that token is not
+valid". The 429 in particular was a token-validity oracle.
+
+What this engine contributes instead is the one thing core cannot do alone.
+Access tokens are stateless, so core "cannot invalidate a stateless JWT before
+its `exp`". This engine's revocation endpoint maintains a `jti` denylist, and
+`IntrospectionsControllerExt` teaches core's endpoint to consult it — so a
+revoked access token introspects as inactive immediately rather than staying
+active until it expires.
+
+### Provider settings
+
+```ruby
+c.provider.id_token_lifetime      = 3600
+c.provider.scopes_supported       = %w[openid profile email offline_access]
+c.provider.claims_supported       = %w[sub iss aud exp iat nonce auth_time at_hash email name email_verified]
+c.provider.subject_types_supported = %w[public]
+c.provider.revocation_enabled     = true   # false renders /api/provider/revoke as 404
+```
+
+The `*_supported` lists are advertised in the discovery document. They describe
+what you are willing to issue — narrow them rather than widen them.
+
+## Development
+
+```bash
+bin/rails app:db:test:prepare        # build the dummy app's test database
+bundle exec rspec
+bundle exec rubocop --config .rubocop.yml
+bundle exec brakeman --no-pager --force
+bundle exec bundler-audit --update
+```
+
+Specs run against `spec/dummy`, a host app mounting this engine alongside
+`StandardId::WebEngine` and `StandardId::ApiEngine`. `spec/dummy/db/schema.rb`
+and the vendored `spec/dummy/db/migrate/*.standard_id.rb` are committed;
+refresh them with:
+
 ```bash
-$ gem install standard_id-provider
+bin/rails app:standard_id:install:migrations
+bin/rails app:db:migrate
 ```
 
+`spec/dummy/config/database.yml` sets `migrations_paths` explicitly. **Leave it
+that way** — without it Rails falls back to the relative default `"db/migrate"`,
+which resolves against RSpec's working directory rather than the dummy app, and
+the suite aborts on permanently-pending migrations.
+
 ## Contributing
-Contribution directions go here.
+
+Bug reports and pull requests are welcome at
+<https://github.com/rarebit-one/standard_id-provider>.
+
+Work happens in a git worktree, never the main checkout — see `CLAUDE.md`.
+Commits are signed. CI runs RuboCop, Brakeman, bundler-audit, the full suite on
+Ruby 4.0.0–4.0.4, and the `compat` job against the latest published
+`standard_id`.
 
 ## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+Available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/standard_id/provider/discovery_controller.rb

@@ -1,33 +1,105 @@
 module StandardId
   module Provider
+    # OpenID Connect Discovery (`GET /.well-known/openid-configuration`).
+    #
+    # ## Why this no longer builds the document by hand
+    #
+    # It used to interpolate every endpoint off the issuer with a hardcoded
+    # `/api` segment:
+    #
+    #     authorization_endpoint: "#{issuer}/api/authorize"
+    #
+    # That is the same defect core fixed in standard_id 0.33.0. It is wrong two
+    # ways at once: it assumes ApiEngine is mounted at exactly `/api`, and it
+    # conflates the ISSUER with the ENDPOINT BASE. Those are different things —
+    # the issuer is a stable security identifier (RFC 8414 §2) that clients
+    # match byte-for-byte against their discovery URL and against the `iss`
+    # claim, while the endpoint base is merely where the endpoints happen to
+    # live. An app whose issuer does not carry the mount path got a document
+    # advertising URLs that 404.
+    #
+    # Resolution is now core's: StandardId::Oauth::DiscoveryResolver reads
+    # `config.oauth.discovery_endpoint_base` and
+    # `config.oauth.discovery_metadata_overrides`, and the document itself is
+    # built by StandardId::Oauth::DiscoveryDocument, so this document cannot
+    # drift from the two core serves.
+    #
+    # ## Setting `discovery_endpoint_base` is not optional for this engine
+    #
+    # Core's own well-known controllers can derive the base from the request,
+    # because they are served from INSIDE the ApiEngine mount, where
+    # `request.script_name` IS the mount path. This controller is served from
+    # the PROVIDER engine's mount, which is a different mount (typically `/`).
+    # `:request` would therefore resolve to the origin root and advertise
+    # `<origin>/oauth/token` for an ApiEngine mounted at `/api`.
+    #
+    # So a host serving this document must say where ApiEngine actually is:
+    #
+    #     c.oauth.discovery_endpoint_base = ->(request:) { "#{request.base_url}/api" }
+    #     # or, for a fixed deployment:
+    #     c.oauth.discovery_endpoint_base = "https://auth.example.com/api"
+    #
+    # That is the hardcoded `/api` moving out of gem code and into host config,
+    # which is the point.
     class DiscoveryController < ApplicationController
       def show
-        render json: openid_configuration
+        resolved = StandardId::Oauth::DiscoveryResolver.resolve(request: request)
+
+        if resolved[:issuer].blank?
+          render json: { error: "Issuer not configured" }, status: :not_found
+          return
+        end
+
+        response.headers["Cache-Control"] = "public, max-age=3600"
+        render json: openid_configuration(resolved)
       end
 
       private
 
-      def openid_configuration
-        issuer = StandardId.config.issuer
+      def openid_configuration(resolved)
+        doc = StandardId::Oauth::DiscoveryDocument.build(
+          resolved[:issuer],
+          endpoint_base: resolved[:endpoint_base],
+          registration_enabled: StandardId.config.oauth.dynamic_registration_enabled,
+          introspection_enabled: StandardId.config.oauth.introspection_enabled
+        )
+
+        doc.merge!(provider_members)
+
+        # Host overrides are applied LAST so they win over the provider members
+        # too, matching how core's controllers treat them.
+        StandardId::Oauth::DiscoveryDocument.apply_overrides!(doc, resolved[:overrides])
+      end
+
+      # Only the OIDC IdP members core has no opinion on.
+      #
+      # Deliberately NOT re-stated here, though the old hand-built document did:
+      #
+      #   * `response_types_supported: %w[code token]` — this engine extends the
+      #     authorization-code flows only. Advertising the implicit flow's
+      #     `token` promised something nothing implements.
+      #   * `code_challenge_methods_supported: %w[S256 plain]` — core enforces
+      #     PKCE with S256 and does not accept `plain`. Advertising it invites a
+      #     downgrade attempt that is then rejected.
+      #   * `id_token_signing_alg_values_supported` — core derives it from
+      #     `config.oauth.signing_algorithm`, which is the same value.
+      #
+      # `revocation_endpoint` IS replaced: core advertises its own
+      # `/oauth/revoke`, but THIS engine's revoke action is the one that writes
+      # the StandardId::Provider::RevokedToken denylist that introspection then
+      # consults. Built from the engine's own route helper so it follows the
+      # mount rather than hardcoding a prefix.
+      def provider_members
         provider_config = StandardId.config.provider
 
         {
-          issuer: issuer,
-          authorization_endpoint: "#{issuer}/api/authorize",
-          token_endpoint: "#{issuer}/api/oauth/token",
-          userinfo_endpoint: "#{issuer}/api/userinfo",
-          jwks_uri: "#{issuer}/api/.well-known/jwks.json",
-          introspection_endpoint: "#{issuer}/api/provider/introspect",
-          revocation_endpoint: "#{issuer}/api/provider/revoke",
+          revocation_endpoint: standard_id_provider.revoke_url(
+            host: request.host_with_port, protocol: request.protocol
+          ),
           scopes_supported: provider_config.scopes_supported,
-          response_types_supported: %w[code token],
-          grant_types_supported: %w[authorization_code client_credentials refresh_token],
           subject_types_supported: provider_config.subject_types_supported,
-          id_token_signing_alg_values_supported: [ StandardId::JwtService.algorithm ],
-          token_endpoint_auth_methods_supported: %w[client_secret_basic client_secret_post],
-          claims_supported: provider_config.claims_supported,
-          code_challenge_methods_supported: %w[S256 plain]
-        }.compact
+          claims_supported: provider_config.claims_supported
+        }
       end
     end
   end

data/app/controllers/standard_id/provider/revocation_controller.rb

@@ -10,6 +10,7 @@ module StandardId
                  name: "provider-revoke-ip",
                  store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
 
+      before_action :require_revocation_enabled!
       before_action :authenticate_client!
 
       def create
@@ -33,6 +34,16 @@ module StandardId
 
         head :ok
       end
+
+      private
+
+      # `config.provider.revocation_enabled` was declared from the start and
+      # read by nothing, so the switch silently did not work. Enforced here,
+      # 404 rather than 403 so a disabled endpoint is indistinguishable from
+      # one that does not exist — matching how core gates introspection.
+      def require_revocation_enabled!
+        head(:not_found) unless StandardId.config.provider.revocation_enabled
+      end
     end
   end
 end

data/config/routes.rb

@@ -1,11 +1,15 @@
 StandardId::Provider::Engine.routes.draw do
   scope ".well-known" do
-    get "openid-configuration", to: "discovery#show"
+    get "openid-configuration", to: "discovery#show", as: :openid_configuration
   end
 
   scope "api/provider" do
-    post "introspect", to: "introspection#create"
-    post "revoke", to: "revocation#create"
+    # NOTE: there is deliberately no `introspect` route here any more. Core's
+    # RFC 7662 endpoint (POST /oauth/introspect, gated on
+    # `config.oauth.introspection_enabled`) is the one endpoint, and this engine
+    # contributes its denylist into it — see
+    # StandardId::Provider::Extensions::IntrospectionsControllerExt.
+    post "revoke", to: "revocation#create", as: :revoke
     resource :consent, only: [ :show, :create, :destroy ], controller: :consent
   end
 end

data/lib/generators/standard_id/provider/install/install_generator.rb

@@ -0,0 +1,138 @@
+require "rails/generators"
+
+module StandardId
+  module Provider
+    module Generators
+      # Installs StandardId::Provider in a host Rails application.
+      #
+      # Three steps, each independently skippable:
+      #
+      #   * copies the engine's migrations into db/migrate/
+      #   * writes config/initializers/standard_id_provider.rb
+      #   * mounts the engine in config/routes.rb
+      #
+      # Idempotent: re-running skips pieces that are already installed and says
+      # so. Pass `--skip-*` to opt out of individual steps and `--force` to
+      # overwrite an existing initializer.
+      class InstallGenerator < Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc <<~DESC
+          Installs StandardId::Provider. By default this:
+            * copies the engine's migrations into db/migrate/
+            * writes config/initializers/standard_id_provider.rb
+            * mounts StandardId::Provider::Engine in config/routes.rb
+
+          Use --skip-* flags to opt out of individual steps when re-running on
+          an existing install. The generator is idempotent — already-installed
+          pieces are skipped with a clear message. Pass --force to overwrite an
+          existing initializer.
+
+          Run `rails db:migrate` afterwards.
+        DESC
+
+        class_option :skip_migrations, type: :boolean, default: false,
+          desc: "Do not copy the engine's migrations into db/migrate"
+        class_option :skip_initializer, type: :boolean, default: false,
+          desc: "Do not write config/initializers/standard_id_provider.rb"
+        class_option :skip_routes, type: :boolean, default: false,
+          desc: "Do not mount StandardId::Provider::Engine in config/routes.rb"
+        class_option :mount_path, type: :string, default: "/",
+          desc: "Path to mount StandardId::Provider::Engine at"
+        class_option :force, type: :boolean, default: false,
+          desc: "Overwrite config/initializers/standard_id_provider.rb if it already exists"
+
+        # Copies the engine's migrations with the same `.standard_id_provider`
+        # suffix `rails standard_id_provider:install:migrations` uses, so the
+        # two are interchangeable and neither double-installs the other's work.
+        # Done in-process rather than by shelling out to that rake task so the
+        # generator stays testable and does not need a booted host app.
+        def copy_migrations
+          if options[:skip_migrations]
+            say_status("skip", "db/migrate (--skip-migrations)", :yellow)
+            return
+          end
+
+          if existing_migrations.any?
+            say_status(
+              "identical",
+              "StandardId::Provider migrations already present (#{existing_migrations.size}), skipping",
+              :blue
+            )
+            return
+          end
+
+          engine_migrations.each_with_index do |source, index|
+            name = File.basename(source, ".rb").sub(/\A\d+_/, "")
+            copy_file source, "db/migrate/#{migration_number(index)}_#{name}.standard_id_provider.rb"
+          end
+        end
+
+        def copy_initializer
+          path = "config/initializers/standard_id_provider.rb"
+
+          if options[:skip_initializer]
+            say_status("skip", "#{path} (--skip-initializer)", :yellow)
+            return
+          end
+
+          if File.exist?(File.join(destination_root, path)) && !options[:force]
+            say_status("identical", "#{path} (already exists; pass --force to overwrite)", :blue)
+            return
+          end
+
+          template "initializer.rb.erb", path, force: options[:force]
+        end
+
+        def mount_engine
+          routes_path = "config/routes.rb"
+
+          if options[:skip_routes]
+            say_status("skip", "#{routes_path} (--skip-routes)", :yellow)
+            return
+          end
+
+          unless File.exist?(File.join(destination_root, routes_path))
+            say_status("warn", "#{routes_path} not found; mount the engine yourself", :red)
+            return
+          end
+
+          if File.read(File.join(destination_root, routes_path)).include?("StandardId::Provider::Engine")
+            say_status("identical", "#{routes_path} (engine already mounted)", :blue)
+            return
+          end
+
+          route(%(mount StandardId::Provider::Engine => "#{options[:mount_path]}"))
+        end
+
+        def print_next_steps
+          say ""
+          say "StandardId::Provider installed. Next:", :green
+          say "  1. rails db:migrate"
+          say "  2. Set config.oauth.discovery_endpoint_base in your StandardId"
+          say "     initializer — this engine's discovery document cannot detect"
+          say "     the ApiEngine mount on its own. See the README."
+          say "  3. Set config.oauth.introspection_enabled = true if you want the"
+          say "     RFC 7662 endpoint (it is off by default in standard_id)."
+          say ""
+        end
+
+        no_commands do
+          def existing_migrations
+            Dir.glob(File.join(destination_root, "db/migrate/*.standard_id_provider.rb"))
+          end
+
+          def engine_migrations
+            Dir.glob(File.expand_path("../../../../../db/migrate/*.rb", __dir__)).sort
+          end
+
+          # Migrations are ordered among themselves and must not collide, hence
+          # the index offset. `install:migrations` does the same thing.
+          def migration_number(index)
+            (Time.now.utc + index).strftime("%Y%m%d%H%M%S")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/generators/standard_id/provider/install/templates/initializer.rb.erb

@@ -0,0 +1,56 @@
+# StandardId::Provider — OpenID Connect Identity Provider addon for StandardId.
+#
+# This engine EXTENDS standard_id rather than standing alone: it prepends into
+# StandardId's OAuth flow classes and contributes its token denylist into
+# StandardId's introspection endpoint. Your `standard_id.rb` initializer is
+# still the primary configuration surface; the settings below are the ones this
+# engine adds, plus the two core settings a provider deployment must revisit.
+
+StandardId.configure do |c|
+  # --- Settings this engine adds -------------------------------------------
+
+  # Lifetime of issued ID tokens, in seconds.
+  # c.provider.id_token_lifetime = 3600
+
+  # Advertised in the discovery document. These describe what YOU are willing
+  # to issue — narrow them rather than widen them.
+  # c.provider.scopes_supported = %w[openid profile email offline_access]
+  # c.provider.claims_supported = %w[sub iss aud exp iat nonce auth_time at_hash email name email_verified]
+  # c.provider.subject_types_supported = %w[public]
+
+  # RFC 7009 token revocation at POST <provider mount>/api/provider/revoke.
+  # When false the endpoint renders 404, indistinguishable from one that does
+  # not exist. This is the endpoint that writes the RevokedToken denylist, so
+  # turning it off means access tokens cannot be revoked before their exp.
+  # c.provider.revocation_enabled = true
+
+  # --- Core settings a provider deployment must revisit --------------------
+
+  # REQUIRED for discovery. The issuer is a stable security identifier
+  # (RFC 8414 §2); clients match it byte-for-byte against their discovery URL
+  # and against the `iss` claim of issued tokens.
+  # c.issuer = "https://auth.example.com"
+
+  # REQUIRED for discovery, and easy to miss. This engine's discovery document
+  # is served from the PROVIDER engine's mount, so — unlike core's own
+  # well-known controllers — it cannot read the ApiEngine mount out of
+  # SCRIPT_NAME. Tell it where the endpoints actually live, or the document
+  # will advertise URLs that 404.
+  #
+  #   c.oauth.discovery_endpoint_base = ->(request:) { "#{request.base_url}/api" }
+  #   # or, for a fixed deployment:
+  #   c.oauth.discovery_endpoint_base = "https://auth.example.com/api"
+
+  # RFC 7662 introspection lives on CORE's endpoint (POST /oauth/introspect),
+  # which is OFF by default — it 404s until you opt in. This engine contributes
+  # its RevokedToken denylist into it, so a revoked access token introspects as
+  # inactive rather than staying active until its exp.
+  # c.oauth.introspection_enabled = true
+
+  # Members that cannot be derived — a host-owned authorization shim, a
+  # deliberately narrower scope list. Applied LAST, so they win over everything
+  # above. Setting `issuer` here raises; use c.issuer.
+  # c.oauth.discovery_metadata_overrides = {
+  #   authorization_endpoint: ->(ctx) { "#{ctx[:origin]}/oauth/authorize" }
+  # }
+end

data/lib/standard_id/provider/config/schema.rb

@@ -4,7 +4,14 @@ StandardId::ConfigSchema.define do
     field :scopes_supported, type: :array, default: -> { %w[openid profile email offline_access] }
     field :claims_supported, type: :array, default: -> { %w[sub iss aud exp iat nonce auth_time at_hash email name email_verified] }
     field :subject_types_supported, type: :array, default: -> { %w[public] }
-    field :introspection_enabled, type: :boolean, default: true
+    # NOTE: there is deliberately no `introspection_enabled` here any more.
+    # It was declared, documented as a switch, and never read by anything —
+    # the endpoint it claimed to gate was always on. Introspection is now
+    # core's endpoint, gated by `StandardId.config.oauth.introspection_enabled`
+    # (which defaults to FALSE — a provider deployment must opt in).
+    #
+    # `revocation_enabled` had the same defect and is now actually enforced by
+    # StandardId::Provider::RevocationController.
     field :revocation_enabled, type: :boolean, default: true
   end
 end

data/lib/standard_id/provider/engine.rb

@@ -20,6 +20,17 @@ module StandardId
           StandardId::Provider::Extensions::AuthorizationCodeFlowExt
         )
       end
+
+      # Controllers are reloadable, so this cannot live in the initializer
+      # above: referencing the constant there would pin the boot-time class and
+      # every `reload!` in development would drop the extension. `to_prepare`
+      # runs on each reload, and `prepend` of an already-prepended module is a
+      # no-op, so re-running it is free.
+      config.to_prepare do
+        StandardId::Api::Oauth::IntrospectionsController.prepend(
+          StandardId::Provider::Extensions::IntrospectionsControllerExt
+        )
+      end
     end
   end
 end

data/lib/standard_id/provider/extensions/introspections_controller_ext.rb

@@ -0,0 +1,60 @@
+module StandardId
+  module Provider
+    module Extensions
+      # Teaches core's RFC 7662 endpoint (`POST /oauth/introspect`,
+      # StandardId::Api::Oauth::IntrospectionsController) about this engine's
+      # access-token denylist.
+      #
+      # ## Why this replaced a second introspection endpoint
+      #
+      # This gem used to ship its own `POST /api/provider/introspect`. Since
+      # standard_id 0.33.0 core has one too, and core's is strictly more
+      # RFC-conformant:
+      #
+      #   * RFC 7662 §2.2 — every failure mode renders `{"active": false}` and
+      #     NOTHING else. The provider's raised InvalidClientError on bad client
+      #     credentials, answering 401 with an error body: a caller could tell
+      #     "your credentials are wrong" from "that token is not valid".
+      #   * The provider's rate limiter answered 429, which turns the throttle
+      #     into a token-validity oracle — probe until throttled, then read the
+      #     status code rather than the body. Core's renders the ordinary
+      #     inactive response instead, deliberately.
+      #   * Core's is 404-gated behind `config.oauth.introspection_enabled`, so
+      #     an endpoint that answers questions about other people's tokens is
+      #     not exposed by accident. The provider's was always on — and its own
+      #     `config.provider.introspection_enabled` flag was never read.
+      #
+      # Only one thing was worth keeping: core cannot see
+      # StandardId::Provider::RevokedToken. Core says so itself — access tokens
+      # are stateless, "this engine cannot invalidate a stateless JWT before its
+      # exp". This engine's revocation endpoint maintains exactly the jti
+      # denylist that makes that possible. So rather than run two endpoints with
+      # different answers, the denylist is contributed INTO core's.
+      #
+      # ## Coupling
+      #
+      # `#decode_token` is a private method of a non-public controller. That is
+      # the same bargain the rest of this gem already makes (see
+      # StandardId::Provider::Engine), and the reason the gemspec pins
+      # `standard_id` to `~> 0.33` with a `compat` CI job watching it.
+      #
+      # Returning nil is the whole mechanism: core already treats a nil decode
+      # as inactive and renders the bare `{"active": false}`, so a denylisted
+      # token is indistinguishable from a forged one — which is what RFC 7662
+      # §2.2 wants.
+      module IntrospectionsControllerExt
+        private
+
+        def decode_token(token)
+          payload = super
+          return nil if payload.nil?
+
+          jti = payload[:jti]
+          return nil if jti.present? && StandardId::Provider::RevokedToken.revoked?(jti)
+
+          payload
+        end
+      end
+    end
+  end
+end

data/lib/standard_id/provider/version.rb

@@ -1,5 +1,5 @@
 module StandardId
   module Provider
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end

data/lib/standard_id/provider.rb

@@ -7,6 +7,7 @@ require "standard_id/provider/extensions/token_grant_flow_ext"
 require "standard_id/provider/extensions/authorization_flow_ext"
 require "standard_id/provider/extensions/traditional_code_grant_ext"
 require "standard_id/provider/extensions/authorization_code_flow_ext"
+require "standard_id/provider/extensions/introspections_controller_ext"
 require "standard_id/provider/engine"
 
 module StandardId

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id-provider
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.33'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.33'
 description: 'Extends StandardId with full OIDC Identity Provider capabilities: ID
   tokens, consent management, token introspection, token revocation, and discovery.'
 email:
@@ -52,7 +52,6 @@ files:
 - app/controllers/standard_id/provider/application_controller.rb
 - app/controllers/standard_id/provider/consent_controller.rb
 - app/controllers/standard_id/provider/discovery_controller.rb
-- app/controllers/standard_id/provider/introspection_controller.rb
 - app/controllers/standard_id/provider/revocation_controller.rb
 - app/helpers/standard_id/provider/application_helper.rb
 - app/jobs/standard_id/provider/application_job.rb
@@ -64,11 +63,14 @@ files:
 - config/routes.rb
 - db/migrate/20260312000001_create_standard_id_consent_grants.rb
 - db/migrate/20260312000002_create_standard_id_revoked_tokens.rb
+- lib/generators/standard_id/provider/install/install_generator.rb
+- lib/generators/standard_id/provider/install/templates/initializer.rb.erb
 - lib/standard_id/provider.rb
 - lib/standard_id/provider/config/schema.rb
 - lib/standard_id/provider/engine.rb
 - lib/standard_id/provider/extensions/authorization_code_flow_ext.rb
 - lib/standard_id/provider/extensions/authorization_flow_ext.rb
+- lib/standard_id/provider/extensions/introspections_controller_ext.rb
 - lib/standard_id/provider/extensions/token_grant_flow_ext.rb
 - lib/standard_id/provider/extensions/traditional_code_grant_ext.rb
 - lib/standard_id/provider/id_token_service.rb

data/app/controllers/standard_id/provider/introspection_controller.rb

@@ -1,50 +0,0 @@
-module StandardId
-  module Provider
-    class IntrospectionController < ApplicationController
-      # Throttle by IP (30 per 15 min) BEFORE client authentication so this
-      # credential-guessable RFC 7662 endpoint can't be brute-forced. Override
-      # with RATE_LIMIT_INTROSPECT_PER_IP.
-      rate_limit to: (ENV["RATE_LIMIT_INTROSPECT_PER_IP"] || 30).to_i,
-                 within: 15.minutes,
-                 by: -> { request.remote_ip },
-                 name: "provider-introspect-ip",
-                 store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
-
-      before_action :authenticate_client!
-
-      def create
-        token = params[:token]
-
-        if token.blank?
-          render json: { active: false }
-          return
-        end
-
-        payload = StandardId::JwtService.decode(token)
-
-        if payload.nil?
-          render json: { active: false }
-          return
-        end
-
-        if payload[:jti].present? && RevokedToken.revoked?(payload[:jti])
-          render json: { active: false }
-          return
-        end
-
-        render json: {
-          active: true,
-          sub: payload[:sub],
-          client_id: payload[:client_id],
-          scope: payload[:scope],
-          iss: payload[:iss],
-          exp: payload[:exp],
-          iat: payload[:iat],
-          jti: payload[:jti],
-          aud: payload[:aud],
-          token_type: "Bearer"
-        }.compact
-      end
-    end
-  end
-end