lcp 0.1.0

data/lib/lcp_ruby/authentication/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module LcpRuby
+  module Authentication
+    # Raised when role resolution returns an empty array and no default_role is configured.
+    # The OIDC callback flow translates this into a friendly "no_role_match" failure page.
+    class NoRoleMatch < StandardError; end
+
+    # Raised when the host's user_provisioner hook returns nil (provisioning gate denied).
+    # Translated to "host_rejected" on the failure page.
+    class HostRejected < StandardError; end
+
+    # Raised when mandatory mapped claims are missing or malformed in the OIDC response.
+    class InvalidClaims < StandardError; end
+
+    # Raised when ProviderRegistry.find is called with a name that has no matching entry.
+    class UnknownProvider < StandardError
+      def initialize(name)
+        super("unknown provider: #{name.inspect}")
+      end
+    end
+
+    # Raised at boot when auth.yml or LcpRuby.configuration violates an OIDC invariant
+    # that cannot be expressed in JSON Schema (e.g. role_source: host without a role_resolver).
+    class ConfigurationError < StandardError; end
+  end
+end

data/lib/lcp_ruby/authentication/http_fetcher.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module LcpRuby
+  module Authentication
+    # Tiny shared HTTP-GET-JSON helper used by ProviderRegistry (discovery
+    # docs) and JwksCache (JWKS docs). Both have identical timeout/SSL needs
+    # and convert non-2xx into ConfigurationError.
+    module HttpFetcher
+      DEFAULT_TIMEOUT = 5 # seconds; both open + read
+
+      class << self
+        # @return [Hash] parsed JSON body
+        # @raise [ConfigurationError] on non-2xx
+        def get_json(url, timeout: DEFAULT_TIMEOUT)
+          uri = URI.parse(url)
+          response = Net::HTTP.start(
+            uri.host, uri.port,
+            use_ssl: uri.scheme == "https",
+            open_timeout: timeout,
+            read_timeout: timeout
+          ) do |http|
+            http.request(Net::HTTP::Get.new(uri.request_uri))
+          end
+          unless response.is_a?(Net::HTTPSuccess)
+            raise ConfigurationError, "GET #{url} failed: HTTP #{response.code}"
+          end
+          JSON.parse(response.body)
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authentication/jwks_cache.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+require "json/jwt"
+require_relative "http_fetcher"
+
+module LcpRuby
+  module Authentication
+    # Per-provider JWKS cache used by bearer validation. Lookup by (provider,
+    # kid); on miss, attempts a rate-limited refresh and re-looks up.
+    #
+    # `refresh!` is rate-limited to one HTTP fetch per minute per provider so a
+    # client crafting unknown-kid values cannot turn LCP into a JWKS-fetch
+    # amplifier. JWKS-level caching lives here rather than on
+    # `omniauth_openid_connect`'s internal cache because bearer validation
+    # needs explicit control over the rate limit.
+    module JwksCache
+      REFETCH_RATE_LIMIT = 60 # seconds between forced refetches per provider
+
+      class << self
+        def key_for(provider, kid:)
+          return nil if kid.nil? || kid.to_s.empty?
+
+          entry = cache[provider.name]
+          return entry[:keys][kid] if entry && entry[:keys].key?(kid)
+
+          begin
+            refresh!(provider)
+          rescue ConfigurationError
+            # Already stamped + logged via the rescue path; treat as miss.
+          end
+          cache[provider.name]&.dig(:keys, kid)
+        end
+
+        # `Concurrent::Map#compute` holds a per-key lock, so concurrent
+        # refreshes for the same provider serialise on one fetch (matters
+        # during key rotation: many requests miss together).
+        # `last_refresh` is stamped on failure too, otherwise an IdP outage
+        # would let an adversary spamming unknown-kid tokens turn each request
+        # into a fetch (no rate limit because the cache stays empty).
+        def refresh!(provider)
+          now = Time.now.to_i
+          fetch_error = nil
+
+          cache.compute(provider.name) do |existing|
+            if existing && now - existing[:last_refresh] < REFETCH_RATE_LIMIT
+              existing
+            else
+              begin
+                { keys: build_keys_by_kid(fetch_jwks(provider)), last_refresh: now }
+              rescue StandardError => e
+                fetch_error = e
+                (existing || { keys: {} }).merge(last_refresh: now)
+              end
+            end
+          end
+
+          raise fetch_error if fetch_error
+          cache[provider.name]
+        end
+
+        def clear!
+          @cache = nil
+        end
+
+        private
+
+        def cache
+          @cache ||= Concurrent::Map.new
+        end
+
+        def fetch_jwks(provider)
+          jwks_uri = ProviderRegistry.discovery_for(provider)["jwks_uri"]
+          if jwks_uri.to_s.empty?
+            raise ConfigurationError, "discovery doc for provider '#{provider.name}' is missing jwks_uri"
+          end
+          HttpFetcher.get_json(jwks_uri)
+        end
+
+        def build_keys_by_kid(jwks_doc)
+          keys = jwks_doc.is_a?(Hash) ? Array(jwks_doc["keys"]) : []
+          keys.each_with_object({}) do |jwk_hash, out|
+            kid = jwk_hash["kid"].to_s
+            next if kid.empty?
+            out[kid] = JSON::JWK.new(jwk_hash)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authentication/oidc_bearer_resolver.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module LcpRuby
+  module Authentication
+    # Glue between BearerJwtVerifier and UserResolver, registered with
+    # LcpRuby::ApiTokens::ResolverRegistry. The matcher (`jwt_shape?`) is
+    # intentionally cheap — it does not verify the signature or look up
+    # keys — so non-JWT tokens (PATs, garbage) fall through to other
+    # resolvers.
+    module OidcBearerResolver
+      # Priority 50 — PAT resolver at 100 always wins for `lcp_pat_*` tokens.
+      RESOLVER_PRIORITY = 50
+
+      class << self
+        # Registers this module with the API-token ResolverRegistry. Called
+        # from the engine initializer at boot and from TestSupport at test
+        # time, so both paths agree on priority/matcher/resolver.
+        def register!
+          LcpRuby::ApiTokens::ResolverRegistry.register(
+            :oidc_bearer,
+            priority: RESOLVER_PRIORITY,
+            matcher:  ->(t) { jwt_shape?(t) },
+            resolver: ->(t) { resolve(t) }
+          )
+        end
+
+        # Cheap shape check. Three dot-separated base64url segments where
+        # the first segment decodes to a JSON object containing an `alg`.
+        # Returns false fast on PATs, opaque tokens, garbage.
+        def jwt_shape?(token)
+          return false if token.nil? || token.to_s.empty?
+
+          parts = token.split(".")
+          return false unless parts.size == 3
+          parts.each { |p| return false if p.empty? }
+
+          header_json = decode_b64url(parts.first)
+          return false unless header_json
+
+          header = JSON.parse(header_json)
+          header.is_a?(Hash) && !header["alg"].to_s.empty?
+        rescue JSON::ParserError
+          false
+        end
+
+        # Returns the resolved User on success, nil otherwise. Swallows the
+        # validator/resolver exceptions that mean "bad token → 401" and the
+        # ConfigurationError raised by `RoleMapper#resolve_db` when
+        # role_source: db is misconfigured (otherwise every API request
+        # would 500 instead of 401). Other exceptions propagate.
+        def resolve(token)
+          claims, provider = BearerJwtVerifier.verify(token)
+          return nil unless claims
+
+          UserResolver.from_claims(claims: claims, provider: provider)
+        rescue HostRejected, NoRoleMatch, InvalidClaims => e
+          Rails.logger.info(
+            "[lcp_ruby] OIDC bearer rejected: #{e.class}: #{e.message}"
+          ) if defined?(Rails)
+          nil
+        rescue ConfigurationError => e
+          Rails.logger.warn(
+            "[lcp_ruby] OIDC bearer rejected — operator misconfiguration: #{e.message}"
+          ) if defined?(Rails)
+          nil
+        end
+
+        private
+
+        def decode_b64url(segment)
+          # Add padding before decoding — base64url segments in JWTs strip
+          # trailing '='. urlsafe_decode64 requires correct padding.
+          padded = segment + "=" * ((4 - segment.length % 4) % 4)
+          Base64.urlsafe_decode64(padded)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authentication/omniauth_builder.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "omniauth"
+require "omniauth_openid_connect"
+# Replaces OmniAuth 2.x's stand-alone request-phase CSRF check with Rails'
+# authenticity token verification (matches the token emitted by `button_to`
+# on the login page). Loaded here so OmniAuth.config.request_validation_phase
+# is patched before any provider strategy runs.
+require "omniauth/rails_csrf_protection"
+
+module LcpRuby
+  module Authentication
+    # Translates Provider value objects into OmniAuth strategy registrations.
+    # Called from the lcp_ruby.omniauth engine initializer at boot.
+    class OmniAuthBuilder
+      DISCOVERY_SUFFIX = %r{/\.well-known/openid-configuration/?\z}.freeze
+
+      class << self
+        # Engine entry point. Registers `OmniAuth::Builder` middleware on the
+        # given Rails application iff at least one OIDC provider is configured,
+        # and sets `OmniAuth.config.path_prefix` so the middleware listens at
+        # the engine-relative `<mount>/auth` URL (NOT the default `/auth`).
+        #
+        # Returns true when middleware was added, false when the call was a
+        # no-op (the gate this method enforces is the contract relied on by
+        # built_in-only / :external / :none deployments — the middleware must
+        # not appear when nothing OIDC is configured).
+        #
+        # Both the path_prefix and the redirect_uri are derived from
+        # `LcpRuby.configuration.mount_path` so they stay in sync. Hosts that
+        # mount the engine at a non-root path MUST set `config.mount_path`
+        # accordingly (validated by AuthValidator at boot for OIDC installs).
+        def install_middleware!(app)
+          return false unless ProviderRegistry.oidc_enabled?
+
+          OmniAuth.config.failure_raise_out_environments = []
+          OmniAuth.config.path_prefix = "#{normalized_mount_path}/auth"
+
+          oidc_providers = ProviderRegistry.all.select(&:oidc?)
+          app.middleware.use OmniAuth::Builder do
+            oidc_providers.each { |provider| OmniAuthBuilder.register(self, provider) }
+          end
+          true
+        rescue LcpRuby::Authentication::ConfigurationError => e
+          # In production, fail loud — a misconfigured auth.yml in prod must
+          # not silently disable OIDC. In dev/test/CI, log a warning and skip
+          # middleware so `rake lcp_ruby:validate` (which depends on
+          # `:environment`) can run and surface the issue in its report.
+          raise if defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+
+          log_skipped_install(e)
+          false
+        end
+
+        # Normalises `LcpRuby.configuration.mount_path` to the form expected
+        # by URL prefixes: empty string for root mounts, leading slash and no
+        # trailing slash otherwise. Single source of truth for both
+        # `path_prefix` and `build_redirect_uri`.
+        def normalized_mount_path
+          mount = LcpRuby.configuration.mount_path.to_s
+          mount = "/#{mount}" unless mount.start_with?("/")
+          mount == "/" ? "" : mount.chomp("/")
+        end
+
+        # Registers an :openid_connect strategy on the given OmniAuth::Builder
+        # using config drawn from the provider entry. Discovery is enabled and
+        # `issuer` is derived from `discovery_url` (strip the well-known suffix);
+        # `omniauth_openid_connect` then calls `Config.discover!(issuer)`, which
+        # appends `/.well-known/openid-configuration` and pulls authorization /
+        # token / userinfo / jwks / end_session endpoints from the IdP.
+        def register(builder, provider)
+          builder.provider :openid_connect,
+                           name: provider.name.to_sym,
+                           issuer: derive_issuer(provider.discovery_url),
+                           discovery: true,
+                           scope: provider.scopes.map(&:to_sym),
+                           response_type: provider.response_type.to_sym,
+                           response_mode: provider.response_mode.to_sym,
+                           send_nonce: true,
+                           pkce: provider.pkce,
+                           client_options: client_options(provider)
+        end
+
+        # Strips the discovery suffix so the strategy receives a bare issuer URL.
+        # Examples:
+        #   https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration
+        #     → https://login.microsoftonline.com/<tenant>/v2.0
+        #   https://accounts.google.com/.well-known/openid-configuration
+        #     → https://accounts.google.com
+        # Falls through unchanged when the suffix isn't present (e.g. some IdPs
+        # publish a non-standard discovery path that the operator pasted as-is).
+        # Raises ConfigurationError on blank input — `omniauth_openid_connect`
+        # would silently accept `issuer: ""` and fail with an opaque error at
+        # the first request; AuthValidator already guarantees a non-blank
+        # discovery_url at boot, so reaching this with a blank value is a bug.
+        def derive_issuer(discovery_url)
+          if discovery_url.to_s.strip.empty?
+            raise LcpRuby::Authentication::ConfigurationError,
+                  "OmniAuthBuilder.derive_issuer requires a non-blank discovery_url"
+          end
+          discovery_url.to_s.sub(DISCOVERY_SUFFIX, "")
+        end
+
+        private
+
+        # Only identifier / secret / redirect_uri belong here — the OmniAuth
+        # `client_options` Hash is a strict allow-list of the values used to
+        # build the underlying OpenIDConnect::Client. Endpoint URLs (scheme,
+        # host, port, authorization_endpoint, token_endpoint, jwks_uri,
+        # end_session_endpoint) are filled in by the discovery step at first
+        # use, so passing them here would either be ignored or override the
+        # IdP's published values.
+        def client_options(provider)
+          {
+            identifier:   provider.client_id,
+            secret:       provider.client_secret,
+            redirect_uri: build_redirect_uri(provider)
+          }.compact
+        end
+
+        # The redirect_uri registered with the IdP. Defaults to
+        # host_url + mount_path + /auth/<provider>/callback. When the
+        # provider has an explicit `redirect_uri:` override (legacy IdP
+        # registrations, reverse-proxy paths, …), it wins verbatim — the
+        # operator is then responsible for routing that URL to the engine
+        # callback (e.g. via a host-level redirect).
+        def build_redirect_uri(provider)
+          return provider.redirect_uri if provider.redirect_uri && !provider.redirect_uri.empty?
+
+          base = LcpRuby.configuration.host_url.to_s.chomp("/")
+          "#{base}#{normalized_mount_path}/auth/#{provider.name}/callback"
+        end
+
+        def log_skipped_install(error)
+          message = "[lcp_ruby] OmniAuth middleware NOT installed — auth.yml is invalid: " \
+                    "#{error.message}. OIDC login will be unavailable until the configuration " \
+                    "is fixed."
+          if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+            Rails.logger.warn(message)
+          else
+            warn(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authentication/provider.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module LcpRuby
+  module Authentication
+    # Value object representing one entry under `auth.providers` in auth.yml.
+    # Built by ProviderRegistry; consumed by OmniAuthBuilder, UserResolver,
+    # RoleMapper, and the login view.
+    Provider = Struct.new(
+      :name,
+      :type,
+      :display_name,
+      :icon,
+      :button_style,
+      :discovery_url,
+      :client_id,
+      :client_secret,
+      :scopes,
+      :pkce,
+      :response_type,
+      :response_mode,
+      :audience,
+      # Optional override for the OIDC redirect_uri sent to the IdP (and
+      # echoed back at token exchange). When unset, OmniAuthBuilder builds
+      # it from `host_url + mount_path + name`. Use this only when an
+      # existing IdP App registration uses a different path than the engine
+      # mount (e.g. legacy registrations, reverse-proxy rewrites).
+      :redirect_uri,
+      :claim_mappings,
+      :role_source,
+      :role_mapping,
+      :default_role,
+      :provisioning,
+      :logout,
+      keyword_init: true
+    ) do
+      VALID_TYPES        = %i[oidc devise].freeze
+      VALID_ROLE_SOURCES = %i[yaml host db].freeze
+
+      DEFAULTS = {
+        scopes: %w[openid profile email].freeze,
+        pkce: true,
+        response_type: "code",
+        response_mode: "query",
+        role_source: :yaml,
+        provisioning: { auto_create: true, update_on_login: [], reject_if_host_missing: false }.freeze,
+        logout: { mode: :local }.freeze
+      }.freeze
+
+      def self.from_hash(raw)
+        h = raw.transform_keys(&:to_sym)
+        instance = new(
+          name:                h.fetch(:name).to_s.freeze,
+          type:                whitelist(h.fetch(:type).to_sym, VALID_TYPES, "type"),
+          display_name:        (h[:display_name] || h.fetch(:name).to_s.titleize).freeze,
+          icon:                h[:icon]&.freeze,
+          button_style:        (h[:button_style] || "secondary").freeze,
+          discovery_url:       h[:discovery_url]&.freeze,
+          client_id:           h[:client_id]&.freeze,
+          client_secret:       h[:client_secret]&.freeze,
+          scopes:              Array(h[:scopes].presence || DEFAULTS[:scopes]).map { |s| s.to_s.freeze }.freeze,
+          pkce:                h.fetch(:pkce, DEFAULTS[:pkce]),
+          response_type:       (h[:response_type] || DEFAULTS[:response_type]).to_s.freeze,
+          response_mode:       (h[:response_mode] || DEFAULTS[:response_mode]).to_s.freeze,
+          audience:            h[:audience]&.freeze,
+          redirect_uri:        h[:redirect_uri]&.freeze,
+          claim_mappings:      symbolize_claim_mappings(h[:claim_mappings] || {}).freeze,
+          role_source:         whitelist((h[:role_source] || DEFAULTS[:role_source]).to_sym, VALID_ROLE_SOURCES, "role_source"),
+          role_mapping:        (h[:role_mapping] || {}).freeze,
+          default_role:        h[:default_role]&.freeze,
+          provisioning:        DEFAULTS[:provisioning].merge((h[:provisioning] || {}).transform_keys(&:to_sym)).freeze,
+          logout:              symbolize_logout(h[:logout]).freeze
+        )
+        instance.freeze
+      end
+
+      # Returns a *new* frozen Provider with the given attribute overrides.
+      # Used by tests so they don't mutate the registry-held singleton.
+      def with(**overrides)
+        attrs = members.each_with_object({}) { |m, h| h[m] = self[m] }
+        attrs.merge!(overrides)
+        self.class.new(**attrs).freeze
+      end
+
+      def self.symbolize_claim_mappings(mappings)
+        mappings.transform_keys(&:to_sym).transform_values(&:to_s)
+      end
+
+      def self.symbolize_logout(raw)
+        merged = DEFAULTS[:logout].merge((raw || {}).transform_keys(&:to_sym))
+        merged.merge(mode: merged[:mode].to_sym)
+      end
+
+      def self.whitelist(value, allowed, field)
+        return value if allowed.include?(value)
+
+        raise ArgumentError, "#{field} must be one of #{allowed.inspect} (got #{value.inspect})"
+      end
+
+      def oidc?
+        type == :oidc
+      end
+
+      def devise?
+        type == :devise
+      end
+    end
+  end
+end