standard_id 0.21.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fea1716449529456cd6e771d62e2565d9100b96d10fb1fb93a4e0e13dc22ca74
-  data.tar.gz: 6403031d85b3a6c50f6a24c1249cb26d3c1b730cc77355d6f5f44946a0a237c4
+  metadata.gz: 7caed55f6e5f6f70b01a7e79dabdc5ad9ddd646535f8c10bbde93158c65e32d9
+  data.tar.gz: 7ca5e3b573b3718e722eb047f14eefffab20263ee374d23f706f278878bcc640
 SHA512:
-  metadata.gz: 33e81b4a0b5d0bf44519c6713e9fd433420362388030fb6bdc22d11e134b342614b92943bfa9b3aacbda9edc4ce63eda3f5345d805514e4db731f35dbfa71d90
-  data.tar.gz: 4e2400b5411341dfdd7f70d5921f5357f4fc7dbcb48e416fe58252267d0a711ac479d35536340202714fbc34bf6af50e0ca15424a27d2ce667f96ad946153225
+  metadata.gz: c68adc74ec092631a1af808cc61ea1d2d8adeb72dbaa70588cd4069edd71b94d57e6ed33f5a9fc5ca4104def616b779e9bbe44f3c9b61e9a861ebdee1eadc946
+  data.tar.gz: 6f10a9a4916737e870798e38c96c53e7767fcf9c4e538bd5c0ca0ee43d21843ec3dff838ee384d1acb6d68336655165fc43cf970e3e8a4e65e5e75cba32fd51f

data/app/controllers/standard_id/api/oauth/registrations_controller.rb

@@ -0,0 +1,91 @@
+module StandardId
+  module Api
+    module Oauth
+      # RFC 7591 Dynamic Client Registration endpoint (POST /oauth/register).
+      #
+      # The endpoint is fully absent (404) unless
+      # `StandardId.config.oauth.dynamic_registration_enabled` is true — an open,
+      # unauthenticated registration endpoint is state-mutating attack surface,
+      # so it is opt-in. When enabled, the controller stays thin: it parses the
+      # JSON client metadata and delegates the RFC 7591 -> ClientApplication
+      # mapping (and the engine's security defaults) to
+      # StandardId::Oauth::ClientRegistration.
+      class RegistrationsController < BaseController
+        public_controller
+
+        # Throttle the open, unauthenticated registration endpoint by IP so an
+        # enabled deployment can't be flooded with ClientApplication rows.
+        rate_limit to: StandardId.config.rate_limits.dynamic_registration_per_ip,
+                   within: 1.hour,
+                   name: "dynamic-registration-ip",
+                   only: :create,
+                   store: StandardId::RateLimitHandling::RATE_LIMIT_STORE
+
+        before_action :require_dynamic_registration_enabled!
+
+        # POST /oauth/register
+        def create
+          result = StandardId::Oauth::ClientRegistration.call(client_metadata)
+          render json: registration_response(result), status: :created
+        end
+
+        private
+
+        # Return 404 (not 403) when the feature is off so the endpoint is
+        # indistinguishable from one that does not exist.
+        def require_dynamic_registration_enabled!
+          head(:not_found) unless StandardId.config.oauth.dynamic_registration_enabled
+        end
+
+        # Permit the full RFC 7591 client metadata document. We hand the raw
+        # values to the service, which whitelists/maps them; the controller does
+        # not need typed param coercion here.
+        def client_metadata
+          params.permit(
+            :client_name,
+            :scope,
+            :token_endpoint_auth_method,
+            redirect_uris: [],
+            grant_types: [],
+            response_types: []
+          ).to_h.tap do |permitted|
+            # `params.permit` drops scalars passed where an array was declared
+            # (and vice versa); fall back to the raw value so the service can
+            # accept either an array or a space-delimited string.
+            %i[redirect_uris grant_types response_types].each do |key|
+              permitted[key] = params[key] if permitted[key].blank? && params[key].present?
+            end
+          end
+        end
+
+        # RFC 7591 §3.2.1 success response. Echoes the registered metadata and,
+        # for confidential clients, the one-time client_secret with
+        # client_secret_expires_at: 0 (never expires).
+        def registration_response(result)
+          client = result.client
+
+          body = {
+            client_id: client.client_id,
+            client_id_issued_at: client.created_at.to_i,
+            client_name: client.name,
+            redirect_uris: client.redirect_uris_array,
+            grant_types: client.grant_types_array,
+            response_types: client.response_types_array,
+            scope: client.scopes,
+            # Echo the registered value (RFC 7591 §3.2.1), not a value derived
+            # from client_type — both client_secret_basic and client_secret_post
+            # are accepted and both work at the token endpoint.
+            token_endpoint_auth_method: result.token_endpoint_auth_method
+          }
+
+          if result.client_secret
+            body[:client_secret] = result.client_secret
+            body[:client_secret_expires_at] = 0
+          end
+
+          body
+        end
+      end
+    end
+  end
+end

data/app/controllers/standard_id/api/well_known/oauth_authorization_server_controller.rb

@@ -27,7 +27,10 @@ module StandardId
           end
 
           response.headers["Cache-Control"] = "public, max-age=3600"
-          render json: StandardId::Oauth::DiscoveryDocument.build(issuer)
+          render json: StandardId::Oauth::DiscoveryDocument.build(
+            issuer,
+            registration_enabled: StandardId.config.oauth.dynamic_registration_enabled
+          )
         end
       end
     end

data/app/controllers/standard_id/api/well_known/openid_configuration_controller.rb

@@ -14,7 +14,10 @@ module StandardId
           end
 
           response.headers["Cache-Control"] = "public, max-age=3600"
-          render json: StandardId::Oauth::DiscoveryDocument.build(issuer)
+          render json: StandardId::Oauth::DiscoveryDocument.build(
+            issuer,
+            registration_enabled: StandardId.config.oauth.dynamic_registration_enabled
+          )
         end
       end
     end

data/config/routes/api.rb

@@ -18,6 +18,11 @@ StandardId::ApiEngine.routes.draw do
       resource :token, only: [:create]
       resource :revoke, only: [:create], controller: :revocations
 
+      # RFC 7591 Dynamic Client Registration -> POST /oauth/register.
+      # The controller returns 404 when oauth.dynamic_registration_enabled is
+      # false, so the endpoint is fully absent unless explicitly enabled.
+      resource :register, only: [:create], controller: :registrations
+
       namespace :callback do
         post ":provider", to: "providers#callback", as: :provider
       end

data/lib/standard_id/config/schema.rb

@@ -270,6 +270,25 @@ StandardId::ConfigSchema.define do
     # Must return a Hash of custom claims to merge into the JWT payload.
     # Example: ->(account:, **) { { channel_id: account.channel_id } }
     field :custom_claims, type: :any, default: nil
+
+    # RFC 7591 Dynamic Client Registration.
+    #
+    # When false (the default), the registration endpoint is fully absent
+    # (`POST /oauth/register` returns 404) and `registration_endpoint` is NOT
+    # advertised in the discovery documents. An open, unauthenticated
+    # registration endpoint is state-mutating attack surface (anyone can mint
+    # OAuth clients), so it is opt-in: a deployment must explicitly turn it on.
+    field :dynamic_registration_enabled, type: :boolean, default: false
+
+    # Callable resolving the polymorphic owner assigned to clients created via
+    # Dynamic Client Registration (the `owner` association on ClientApplication
+    # is required). Example: `-> { Organization.default }`.
+    #
+    # When `dynamic_registration_enabled` is true but this resolver is nil (or
+    # returns nil), registration raises a clear configuration error rather than
+    # silently failing the model's presence validation — so misconfiguration is
+    # caught loudly at request time.
+    field :dynamic_registration_owner, type: :any, default: nil
   end
 
   scope :social do
@@ -308,5 +327,9 @@ StandardId::ConfigSchema.define do
     field :api_passwordless_start_per_ip, type: :integer, default: 10    # per hour
     field :api_passwordless_start_per_target, type: :integer, default: 5 # per 15 minutes
     field :api_token_per_ip, type: :integer, default: 30                 # per 15 minutes
+
+    # Dynamic client registration (RFC 7591) — throttle the open registration
+    # endpoint by IP so an enabled deployment can't be flooded with client rows.
+    field :dynamic_registration_per_ip, type: :integer, default: 10      # per hour
   end
 end

data/lib/standard_id/errors.rb

@@ -110,6 +110,18 @@ module StandardId
     def oauth_error_code = :unsupported_response_type
   end
 
+  # RFC 7591 §3.2.2 client registration errors. Both render as HTTP 400 with
+  # an `error` of `invalid_redirect_uri` / `invalid_client_metadata` and an
+  # `error_description`. They subclass OAuthError so the existing OAuth error
+  # handling renders them in the standard error shape.
+  class InvalidRedirectUriError < OAuthError
+    def oauth_error_code = :invalid_redirect_uri
+  end
+
+  class InvalidClientMetadataError < OAuthError
+    def oauth_error_code = :invalid_client_metadata
+  end
+
   # Lifecycle hook errors
   class AuthenticationDenied < StandardError; end
 

data/lib/standard_id/oauth/client_registration.rb

@@ -0,0 +1,205 @@
+require "securerandom"
+
+module StandardId
+  module Oauth
+    # RFC 7591 Dynamic Client Registration.
+    #
+    # Maps a client metadata document (the JSON body of POST /oauth/register)
+    # onto a StandardId::ClientApplication, applying the engine's security
+    # defaults (PKCE-forced public clients, S256, consent-by-default) and a
+    # conservative whitelist of grant/response types. Keeps the controller thin
+    # in the same flow-object style as the other lib/standard_id/oauth/ objects.
+    #
+    # On success #call returns a Result carrying the persisted client plus the
+    # one-time plaintext secret (confidential clients only); on a metadata or
+    # redirect-uri problem it raises the matching RFC 7591 §3.2.2 error
+    # (InvalidRedirectUriError / InvalidClientMetadataError), which the
+    # controller renders as HTTP 400. A nil owner resolver while the feature is
+    # enabled raises ConfigurationError (a host-app bug, not client input).
+    class ClientRegistration
+      # RFC 7591 grant_types we support. M2M (client_credentials) is deliberately
+      # excluded from DCR — self-registered clients are public/interactive.
+      ALLOWED_GRANT_TYPES = %w[authorization_code refresh_token].freeze
+      # Only the authorization-code response type is supported.
+      ALLOWED_RESPONSE_TYPES = %w[code].freeze
+      # token_endpoint_auth_method -> client_type mapping.
+      PUBLIC_AUTH_METHOD = "none".freeze
+      CONFIDENTIAL_AUTH_METHODS = %w[client_secret_basic client_secret_post].freeze
+      DEFAULT_AUTH_METHOD = PUBLIC_AUTH_METHOD
+      DEFAULT_SCOPE = "openid profile email".freeze
+
+      # Minimal result object mirroring the gem's `result.success?` /
+      # `result.value` convention. `client_secret` is the one-time plaintext for
+      # confidential clients (nil for public clients).
+      Result = Struct.new(:client, :client_secret, :token_endpoint_auth_method, keyword_init: true) do
+        def success? = true
+        def value = client
+      end
+
+      # @param metadata [Hash] RFC 7591 client metadata (symbolized or stringified keys)
+      def initialize(metadata)
+        @metadata = (metadata || {}).to_h.symbolize_keys
+      end
+
+      def self.call(metadata)
+        new(metadata).call
+      end
+
+      def call
+        attrs = mapped_attributes
+        client = StandardId::ClientApplication.new(attrs)
+
+        secret_plaintext = nil
+        StandardId::ClientApplication.transaction do
+          client.save!
+          if client.confidential?
+            secret_plaintext = SecureRandom.hex(32)
+            client.create_client_secret!(
+              name: "Dynamic Registration Secret",
+              client_secret: secret_plaintext
+            )
+          end
+        end
+
+        Result.new(client: client, client_secret: secret_plaintext, token_endpoint_auth_method: auth_method)
+      rescue ActiveRecord::RecordInvalid => e
+        raise_for(e.record)
+      end
+
+      private
+
+      attr_reader :metadata
+
+      def mapped_attributes
+        {
+          owner: resolve_owner!,
+          name: client_name,
+          redirect_uris: redirect_uris,
+          grant_types: grant_types,
+          response_types: response_types,
+          scopes: scope,
+          client_type: client_type,
+          require_pkce: require_pkce?,
+          code_challenge_methods: code_challenge_methods,
+          require_consent: true
+        }
+      end
+
+      # redirect_uris is REQUIRED (RFC 7591 §2). We pass the raw value through to
+      # the model and let its redirect-uri validation surface an invalid_redirect_uri
+      # error — keeping a single source of truth for URI rules.
+      def redirect_uris
+        Array(metadata[:redirect_uris]).map { |u| u.to_s.strip }.reject(&:blank?).join(" ")
+      end
+
+      def client_name
+        name = metadata[:client_name].to_s.strip
+        name.presence || "Dynamically Registered Client #{SecureRandom.hex(4)}"
+      end
+
+      # Whitelist grant_types. Any value outside ALLOWED_GRANT_TYPES is rejected
+      # as invalid_client_metadata (RFC 7591 §3.2.2). Absent -> authorization_code.
+      def grant_types
+        requested = list_param(:grant_types)
+        return "authorization_code" if requested.empty?
+
+        disallowed = requested - ALLOWED_GRANT_TYPES
+        if disallowed.any?
+          raise StandardId::InvalidClientMetadataError,
+            "Unsupported grant_types: #{disallowed.join(', ')}. Allowed: #{ALLOWED_GRANT_TYPES.join(', ')}"
+        end
+
+        requested.join(" ")
+      end
+
+      def response_types
+        requested = list_param(:response_types)
+        return "code" if requested.empty?
+
+        disallowed = requested - ALLOWED_RESPONSE_TYPES
+        if disallowed.any?
+          raise StandardId::InvalidClientMetadataError,
+            "Unsupported response_types: #{disallowed.join(', ')}. Allowed: #{ALLOWED_RESPONSE_TYPES.join(', ')}"
+        end
+
+        requested.join(" ")
+      end
+
+      def scope
+        scope = metadata[:scope].to_s.strip
+        scope.presence || DEFAULT_SCOPE
+      end
+
+      def auth_method
+        method = metadata[:token_endpoint_auth_method].to_s.strip
+        method.presence || DEFAULT_AUTH_METHOD
+      end
+
+      def client_type
+        method = auth_method
+        return "public" if method == PUBLIC_AUTH_METHOD
+        return "confidential" if CONFIDENTIAL_AUTH_METHODS.include?(method)
+
+        raise StandardId::InvalidClientMetadataError,
+          "Unsupported token_endpoint_auth_method: #{method.inspect}. " \
+          "Allowed: #{(CONFIDENTIAL_AUTH_METHODS + [PUBLIC_AUTH_METHOD]).join(', ')}"
+      end
+
+      # Public clients are always forced onto PKCE/S256 (the model also validates
+      # this). Confidential clients also default to PKCE here for defense in depth.
+      def require_pkce?
+        true
+      end
+
+      def code_challenge_methods
+        "S256"
+      end
+
+      def resolve_owner!
+        resolver = StandardId.config.oauth.dynamic_registration_owner
+        unless resolver.respond_to?(:call)
+          raise StandardId::ConfigurationError,
+            "oauth.dynamic_registration_owner must be set to a callable resolving the " \
+            "client owner when oauth.dynamic_registration_enabled is true " \
+            "(e.g. -> { Organization.default })"
+        end
+
+        owner = resolver.call
+        if owner.nil?
+          raise StandardId::ConfigurationError,
+            "oauth.dynamic_registration_owner resolved to nil; it must return the " \
+            "polymorphic owner record for dynamically registered clients"
+        end
+
+        owner
+      end
+
+      # Accept either an Array or a space-delimited String for list-shaped
+      # metadata fields (RFC 7591 uses JSON arrays; be lenient with strings too).
+      def list_param(key)
+        value = metadata[key]
+        case value
+        when Array
+          value.map { |v| v.to_s.strip }.reject(&:blank?)
+        else
+          value.to_s.split(/\s+/).map(&:strip).reject(&:blank?)
+        end
+      end
+
+      # Translate an ActiveRecord validation failure into the matching RFC 7591
+      # error. A redirect_uris failure is invalid_redirect_uri; everything else
+      # (including a blank redirect_uris which the model reports as a presence
+      # error) maps to invalid_client_metadata.
+      def raise_for(record)
+        errors = record.errors
+        message = errors.full_messages.join("; ")
+
+        if errors.key?(:redirect_uris)
+          raise StandardId::InvalidRedirectUriError, message.presence || "Invalid redirect_uris"
+        end
+
+        raise StandardId::InvalidClientMetadataError, message.presence || "Invalid client metadata"
+      end
+    end
+  end
+end

data/lib/standard_id/oauth/discovery_document.rb

@@ -20,9 +20,10 @@ module StandardId
 
       # @param issuer [String] the configured issuer (e.g. "https://auth.example.com")
       # @param registration_enabled [Boolean] when true, advertises the RFC 7591
-      #   dynamic client registration endpoint. Defaults to false; the seam is
-      #   kept here so Phase 2 (DCR) can flip it on via config without touching
-      #   either controller. While false, no registration_endpoint is emitted.
+      #   dynamic client registration endpoint. The well-known controllers pass
+      #   `StandardId.config.oauth.dynamic_registration_enabled` here, so the
+      #   `registration_endpoint` is emitted only when DCR is turned on. Defaults
+      #   to false so callers (and tests) that omit it get no registration_endpoint.
       # @return [Hash]
       def build(issuer, registration_enabled: false)
         base = issuer.to_s.chomp("/")

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.21.1"
+  VERSION = "0.22.0"
 end

data/lib/standard_id.rb

@@ -46,6 +46,7 @@ require "standard_id/oauth/subflows/social_login_grant"
 require "standard_id/oauth/passwordless_otp_flow"
 require "standard_id/oauth/discovery_document"
 require "standard_id/oauth/consent_payload"
+require "standard_id/oauth/client_registration"
 require "standard_id/passwordless/base_strategy"
 require "standard_id/passwordless/email_strategy"
 require "standard_id/passwordless/sms_strategy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.21.1
+  version: 0.22.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -132,6 +132,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/registrations_controller.rb
 - app/controllers/standard_id/api/oauth/revocations_controller.rb
 - app/controllers/standard_id/api/oauth/tokens_controller.rb
 - app/controllers/standard_id/api/oidc/logout_controller.rb
@@ -261,6 +262,7 @@ files:
 - lib/standard_id/oauth/authorization_flow.rb
 - lib/standard_id/oauth/base_request_flow.rb
 - lib/standard_id/oauth/client_credentials_flow.rb
+- 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/implicit_authorization_flow.rb