lcp 0.1.0

data/lib/lcp_ruby/authentication/provider_registry.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+require "concurrent/map"
+require_relative "http_fetcher"
+
+module LcpRuby
+  module Authentication
+    # Loads and caches the auth.yml provider registry. Single source of truth
+    # for OmniAuthBuilder, the adaptive login view, the callbacks controller,
+    # and (Phase 2) the bearer middleware.
+    #
+    # Lifecycle:
+    #   - First access (`all`, `oidc_enabled?`, ...) reads & validates auth.yml.
+    #   - Result is memoized; subsequent accesses are O(1) hash lookups.
+    #   - `reload!` invalidates both the provider list and the discovery cache.
+    #     Used by tests and by Engine.reload!.
+    class ProviderRegistry
+      DISCOVERY_TTL = 3600 # seconds
+
+      class << self
+        # Returns Array<Provider>. Triggers a one-time load of auth.yml on first call.
+        def all
+          @all ||= load!
+        end
+
+        def find(name)
+          find_by(name) or raise UnknownProvider.new(name)
+        end
+
+        # Non-raising sibling of `find`. Returns nil when the provider isn't registered.
+        def find_by(name)
+          all.find { |p| p.name == name.to_s }
+        end
+
+        # The provider that should be highlighted on the login page.
+        # Falls back to the first listed provider when no default_provider key is set.
+        def default
+          name = raw_config["default_provider"]&.to_s
+          (name && find_by(name)) || all.first
+        end
+
+        def oidc_providers
+          @oidc_providers ||= all.select(&:oidc?)
+        end
+
+        def oidc_enabled?
+          oidc_providers.any?
+        end
+
+        def default_auto_redirect?
+          !!raw_config["default_provider_auto_redirect"]
+        end
+
+        # Whether at least one Devise (built_in) provider entry exists.
+        def devise_enabled?
+          all.any?(&:devise?)
+        end
+
+        # Whether the login page should render the password form. True when
+        # there's a Devise provider entry, OR when auth.yml is absent entirely
+        # (legacy :built_in-only setups). Drives both `SessionsController#new`
+        # and the `#create` guard so they can't disagree.
+        def password_sign_in_allowed?
+          all.empty? || devise_enabled?
+        end
+
+        # Force-refresh of providers and discovery cache. Tests call this in
+        # `before` hooks after stubbing auth.yml on disk.
+        def reload!
+          @all = nil
+          @oidc_providers = nil
+          @raw_root = nil
+          @load_error = nil
+          discovery_cache.clear
+          self
+        end
+
+        # Last ConfigurationError encountered while loading auth.yml, or nil
+        # when the load succeeded (or hasn't been attempted). Set by `load!`
+        # alongside the raise so non-raising introspection is possible —
+        # `ConfigurationValidator#validate_auth_yml` reads this to surface
+        # auth.yml problems in the validate report without re-parsing YAML.
+        def load_error
+          @load_error
+        end
+
+        # Returns the OIDC provider whose discovery `issuer` matches `iss`,
+        # or nil. Iterates `oidc_providers`, but `discovery_for` is itself
+        # cached for an hour — so per-request cost is N hash lookups rather
+        # than N HTTP calls. A misconfigured provider must not block tokens
+        # from other working providers, so transient discovery errors are
+        # logged and skipped.
+        def find_by_issuer(iss)
+          return nil if iss.nil? || iss.to_s.empty?
+
+          oidc_providers.find do |p|
+            doc = discovery_for(p)
+            doc.is_a?(Hash) && doc["issuer"] == iss
+          rescue ConfigurationError, SocketError, Timeout::Error,
+                 Net::HTTPError, OpenSSL::SSL::SSLError, JSON::ParserError => e
+            Rails.logger.info(
+              "[lcp_ruby] ProviderRegistry skipping provider '#{p.name}' " \
+              "in issuer match: #{e.class}: #{e.message}"
+            ) if defined?(Rails)
+            false
+          end
+        end
+
+        # Test seam: replace a frozen Provider in the memoized list with a
+        # variant produced via `provider.with(...)`. Ensures specs don't
+        # need to know the internal storage shape and never mutate frozen
+        # registry entries directly.
+        def replace_for_test!(replacement)
+          load! unless @all
+          @all = @all.map { |p| p.name == replacement.name ? replacement : p }
+          @oidc_providers = nil
+          replacement
+        end
+
+        # Returns the discovery document (Hash) for an OIDC provider, fetched
+        # lazily and cached for DISCOVERY_TTL seconds. Used by OmniAuthBuilder
+        # and the RP-initiated logout flow.
+        #
+        # `Concurrent::Map#compute` holds a per-key lock for the duration of
+        # the block, so two threads racing on the same provider serialise on
+        # the fetch — the first issues the HTTP request, the second sees the
+        # populated entry and skips. Without this, both threads would miss
+        # the cache and both would fetch (idempotent but wasteful, and worse
+        # under JWKS where misses are an attack-amplification vector).
+        def discovery_for(provider)
+          now = Time.now.to_i
+          entry = discovery_cache.compute(provider.name) do |existing|
+            if existing && existing[:fetched_at] + DISCOVERY_TTL > now
+              existing
+            else
+              { doc: fetch_discovery(provider.discovery_url), fetched_at: now }
+            end
+          end
+          entry[:doc]
+        end
+
+        # Path to auth.yml. Falls back to LcpRuby.configuration.metadata_path.
+        def auth_yml_path
+          File.join(LcpRuby.configuration.metadata_path.to_s, "auth.yml")
+        end
+
+        def configured?
+          File.exist?(auth_yml_path)
+        end
+
+        private
+
+        def discovery_cache
+          @discovery_cache ||= Concurrent::Map.new
+        end
+
+        def load!
+          # Memoize raised errors so multiple boot-time callers
+          # (OmniAuthBuilder + Engine.register_oidc_bearer_resolver_if_enabled!)
+          # don't re-parse YAML and re-run AuthValidator on the same broken
+          # config. `reload!` clears @load_error.
+          raise @load_error if @load_error
+
+          return [] if raw_root.empty?
+
+          # Build Provider value objects, but convert the ArgumentError that
+          # `Provider.from_hash` raises on bad enum values (`type: saml`,
+          # `role_source: ldap`) into our typed ConfigurationError. Without
+          # this, schema-level errors that would otherwise be reported by
+          # AuthValidator escape as raw ArgumentError before validation runs.
+          providers = raw_config.fetch("providers", []).map do |entry|
+            begin
+              Provider.from_hash(entry)
+            rescue ArgumentError => e
+              raise ConfigurationError,
+                    "auth.yml: provider #{entry["name"].inspect}: #{e.message}"
+            end
+          end
+          LcpRuby::Metadata::ConfigurationValidator.validate_auth!(raw: raw_root, providers: providers)
+          providers
+        rescue ConfigurationError => e
+          @load_error = e
+          raise
+        end
+
+        # Returns the parsed contents of auth.yml — the inner `auth:` block.
+        def raw_config
+          raw_root.fetch("auth", {})
+        end
+
+        # Returns the full parsed YAML document including the top-level `auth:` key.
+        # Returns {} when auth.yml is absent, empty, or not a Hash.
+        # Raises ConfigurationError with a clear pointer when the file exists
+        # but is malformed (Psych syntax error, ERB error) — surfacing those at
+        # boot is far more useful than letting a Psych stack trace bubble up.
+        # Other errors (e.g. unexpected programmer bugs in this method)
+        # propagate unchanged so they aren't masked.
+        def raw_root
+          @raw_root ||= begin
+            erb = ERB.new(File.read(auth_yml_path)).result
+            parsed = YAML.safe_load(erb, aliases: true) || {}
+            parsed.is_a?(Hash) ? parsed : {}
+          rescue Errno::ENOENT
+            {}
+          rescue Psych::SyntaxError => e
+            raise ConfigurationError,
+                  "auth.yml at #{auth_yml_path} is not valid YAML: #{e.message}"
+          rescue NameError, SyntaxError => e
+            # ERB raises NameError on undefined locals (`<%= ENV[FOO] %>`) and
+            # SyntaxError on bad templates (`<%= 1 + %>`). Wrap so operators
+            # see the file path along with the underlying error class.
+            raise ConfigurationError,
+                  "auth.yml at #{auth_yml_path} could not be loaded: #{e.class}: #{e.message}"
+          end
+        end
+
+        def fetch_discovery(url)
+          HttpFetcher.get_json(url)
+        rescue ConfigurationError => e
+          raise ConfigurationError, "OIDC discovery failed: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authentication/role_mapper.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module LcpRuby
+  module Authentication
+    # Translates IdP claims into LCP role strings according to a Provider's
+    # role_source policy (yaml | host | db). Pure function — no Rails, no DB.
+    #
+    # Returns Array<String>. Raises NoRoleMatch when resolution yields an
+    # empty result and the provider has no default_role.
+    class RoleMapper
+      class << self
+        def call(claims, provider)
+          claim_path = provider.claim_mappings[:roles_from]
+          values     = claim_path ? Array(dig_path(claims, claim_path)).map(&:to_s) : []
+
+          mapped = resolve(provider, values, claims)
+          mapped = [ provider.default_role.to_s ] if mapped.empty? && provider.default_role
+          raise NoRoleMatch, "no roles matched for provider '#{provider.name}'" if mapped.empty?
+          mapped
+        end
+
+        # Walks a dotted JSON path through a string-keyed hash. Returns nil for
+        # missing keys. Used to read nested claims like 'realm_access.roles'
+        # (Keycloak). Callers must hand in claims with string keys throughout —
+        # UserResolver#extract_claims normalises at the boundary.
+        def dig_path(hash, path)
+          hash.dig(*path.to_s.split("."))
+        end
+
+        private
+
+        def resolve(provider, values, claims)
+          case provider.role_source
+          when :yaml
+            resolve_yaml(provider, values)
+          when :host
+            resolve_host(provider, values, claims)
+          when :db
+            resolve_db(provider, values, claims)
+          else
+            raise ConfigurationError, "unknown role_source: #{provider.role_source.inspect}"
+          end
+        end
+
+        def resolve_yaml(provider, values)
+          mapping = provider.role_mapping || {}
+          values.flat_map { |v| Array(mapping[v] || mapping[v.to_sym]) }.compact.map(&:to_s).uniq
+        end
+
+        def resolve_host(provider, values, claims)
+          resolver = LcpRuby.configuration.role_resolver
+          if resolver.nil?
+            raise ConfigurationError,
+                  "provider '#{provider.name}' has role_source: host but " \
+                  "LcpRuby.configuration.role_resolver is not set"
+          end
+          Array(resolver.call(values, provider.name, claims)).map(&:to_s).uniq
+        end
+
+        # Phase 2: DB-backed role mapping. Looks up rows in the
+        # `oidc_role_mapping` model where (provider, claim_value) matches a
+        # claim in `values` and returns the unique `lcp_role` strings. The
+        # model is generated by `rails generate lcp_ruby:oidc_role_mappings`.
+        # Raises ConfigurationError with an actionable message when the model
+        # is not registered (boot-time validator does not enforce this — see
+        # AuthValidator#validate_role_source).
+        def resolve_db(provider, values, _claims)
+          unless LcpRuby.registry.registered?("oidc_role_mapping")
+            raise ConfigurationError,
+                  "provider '#{provider.name}' has role_source: db but the " \
+                  "oidc_role_mapping model is not registered. Run " \
+                  "`rails generate lcp_ruby:oidc_role_mappings` and `db:prepare`."
+          end
+
+          return [] if values.empty?
+
+          claim_name = provider.claim_mappings[:roles_from].to_s
+          # Filter by claim_name as well as claim_value: prevents stale rows
+          # tagged with the old claim path from accidentally matching when a
+          # host changes `claim_mappings.roles_from` (e.g. roles → groups).
+          # When `roles_from` is unset we cannot scope by claim_name, so the
+          # provider config is misconfigured — treat as no mappings.
+          return [] if claim_name.empty?
+
+          LcpRuby.registry.model_for("oidc_role_mapping")
+            .where(provider: provider.name, claim_name: claim_name, claim_value: values)
+            .pluck(:lcp_role)
+            .map(&:to_s)
+            .uniq
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authentication/test_support.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json/jwt"
+require "rspec/mocks"
+
+module LcpRuby
+  module Authentication
+    # Public test-support helper for Phase 2 bearer authentication.
+    #
+    # Lets host-app specs sign valid (and invalid) JWTs that LCP's bearer
+    # pipeline accepts, without spinning up a real IdP or stubbing engine
+    # internals. Loaded only under `Rails.env.test?` — `install_provider!`
+    # raises `NotInTestEnv` everywhere else as defense-in-depth against
+    # accidentally shipping the helper to production.
+    #
+    # Stubs are installed via rspec-mocks's `allow().to receive()`, so they
+    # auto-reset between examples — no manual teardown needed beyond
+    # `TestSupport.reset!` for the per-process keypair / provider cache.
+    #
+    # Usage:
+    #
+    #   require "lcp_ruby/authentication/test_support"
+    #
+    #   RSpec.configure do |config|
+    #     config.before do
+    #       @oidc_signer = LcpRuby::Authentication::TestSupport.install_provider!(
+    #         "entra",
+    #         issuer:   "https://test-issuer.example/",
+    #         audience: "api://lcp-test"
+    #       )
+    #     end
+    #
+    #     config.after { LcpRuby::Authentication::TestSupport.reset! }
+    #   end
+    #
+    #   it "lists deals via OIDC bearer" do
+    #     token = @oidc_signer.sign(sub: "user-1", roles: ["LCP.Admin"])
+    #     get "/api/deals", headers: { "Authorization" => "Bearer #{token}" }
+    #     expect(response).to have_http_status(:ok)
+    #   end
+    #
+    # Negative-case helpers on the Signer:
+    #   signer.sign_expired(sub: "user-1")        # exp in the past
+    #   signer.sign_wrong_audience(sub: "user-1") # aud mismatch
+    #   signer.sign_unknown_kid(sub: "user-1")    # kid not in JWKS
+    #   signer.sign_tampered(sub: "user-1")       # signature mutilated
+    module TestSupport
+      class NotInTestEnv < StandardError; end
+
+      DEFAULT_KID = "test-kid"
+
+      class << self
+        # Installs a synthetic OIDC provider into LCP's caches and returns
+        # a Signer for producing JWTs that the bearer pipeline will accept.
+        # Idempotent across multiple calls within the same example: each
+        # call adds its provider to the stubbed `oidc_providers` list.
+        # Must be called from inside an RSpec example or `before` hook
+        # (rspec-mocks is required).
+        def install_provider!(name, issuer:, audience:, kid: DEFAULT_KID)
+          ensure_test_env!
+          ensure_rspec_mocks!
+          name = name.to_s
+
+          rsa_key    = (keypairs[name] ||= OpenSSL::PKey::RSA.generate(2048))
+          public_jwk = JSON::JWK.new(rsa_key.public_key).merge(kid: kid, use: "sig", alg: "RS256")
+          provider   = build_provider(name: name, audience: audience)
+
+          providers[name] = provider
+          per_provider[name] = { provider: provider, issuer: issuer, kid: kid, public_jwk: public_jwk }
+
+          install_stubs!
+          register_oidc_resolver!
+
+          Signer.new(provider: provider, issuer: issuer, audience: audience, kid: kid, rsa_key: rsa_key)
+        end
+
+        # Clears the per-process provider/keypair cache and the JwksCache.
+        # rspec-mocks auto-resets between examples, so you typically only
+        # need this if you `install_provider!`-loop within a single example.
+        def reset!
+          @providers    = nil
+          @per_provider = nil
+          @keypairs     = nil
+          JwksCache.clear! if defined?(JwksCache)
+        end
+
+        private
+
+        def ensure_test_env!
+          return if defined?(Rails) && Rails.env.test?
+          raise NotInTestEnv,
+                "LcpRuby::Authentication::TestSupport.install_provider! is only " \
+                "available under Rails.env.test? — refusing to install OIDC test stubs."
+        end
+
+        def ensure_rspec_mocks!
+          return if defined?(::RSpec::Mocks) && ::RSpec::Mocks.space &&
+                    ::RSpec::Mocks::ExampleMethods.respond_to?(:declare_double)
+          raise NotInTestEnv,
+                "LcpRuby::Authentication::TestSupport.install_provider! requires " \
+                "rspec-mocks. Call it from inside an example or `before` hook."
+        end
+
+        def providers
+          @providers ||= {}
+        end
+
+        def per_provider
+          @per_provider ||= {}
+        end
+
+        def keypairs
+          @keypairs ||= {}
+        end
+
+        def build_provider(name:, audience:)
+          Provider.from_hash(
+            "name" => name, "type" => "oidc",
+            "discovery_url" => "https://test-#{name}/.well-known/openid-configuration",
+            "client_id" => "test-#{name}-client",
+            "client_secret" => "test-#{name}-secret",
+            "audience" => audience,
+            "claim_mappings" => { "external_id" => "sub", "email" => "email", "name" => "name", "roles_from" => "roles" },
+            "role_source" => "yaml",
+            "role_mapping" => { "LCP.Admin" => "admin", "LCP.Sales" => "sales" },
+            "default_role" => "viewer",
+            "provisioning" => { "auto_create" => true, "update_on_login" => [ "email", "name" ] }
+          )
+        end
+
+        # The engine's `lcp_ruby.oidc_bearer` initializer registers the OIDC
+        # bearer resolver only at app boot, gated on whether auth.yml has at
+        # least one provider with non-empty `audience`. Tests typically boot
+        # with no auth.yml, so we register here on demand.
+        def register_oidc_resolver!
+          OidcBearerResolver.register!
+        end
+
+        # Calls rspec-mocks' allow() / receive() via Stubber (which mixes in
+        # RSpec::Mocks::ExampleMethods). Reapplies on every install_provider!
+        # so a second provider registration extends the oidc_providers list
+        # rather than replacing it. Per-example stubs auto-reset between
+        # examples, so a separate teardown is not needed.
+        def install_stubs!
+          all = providers.values
+          s = Stubber.new
+
+          s.stub_return(ProviderRegistry, :oidc_enabled?, true)
+          s.stub_return(ProviderRegistry, :configured?,    true)
+          s.stub_return(ProviderRegistry, :oidc_providers, all)
+
+          # Install a permissive default first so unmatched (provider, kid)
+          # combinations return nil rather than raising on unexpected args.
+          # The specific .with(...) stubs registered below take precedence
+          # when their args match.
+          s.stub_return(JwksCache, :key_for, nil)
+
+          per_provider.each_value do |entry|
+            s.stub_with_args(
+              ProviderRegistry, :discovery_for,
+              args: [ entry[:provider] ],
+              return_value: { "issuer" => entry[:issuer], "jwks_uri" => "https://test/jwks/#{entry[:provider].name}" }
+            )
+
+            s.stub_with_args(
+              JwksCache, :key_for,
+              args: [ entry[:provider] ],
+              kwargs: { kid: entry[:kid] },
+              return_value: entry[:public_jwk]
+            )
+          end
+        end
+      end
+
+      # Thin wrapper over RSpec::Mocks::ExampleMethods. Keeps mock primitives
+      # out of the TestSupport public surface.
+      class Stubber
+        include ::RSpec::Mocks::ExampleMethods
+
+        def stub_return(target, method_name, value)
+          allow(target).to receive(method_name).and_return(value)
+        end
+
+        def stub_with_args(target, method_name, args:, kwargs: nil, return_value:)
+          stub = allow(target).to receive(method_name)
+          stub = if kwargs
+            stub.with(*args, **kwargs)
+          else
+            stub.with(*args)
+          end
+          stub.and_return(return_value)
+        end
+      end
+
+      # Produces signed RS256 JWTs with sensible defaults plus convenience
+      # methods for rejection cases. All defaults are derived from the
+      # provider/issuer/audience passed to install_provider!; per-claim
+      # overrides via kwargs.
+      class Signer
+        DEFAULT_TTL = 3600 # seconds
+
+        def initialize(provider:, issuer:, audience:, kid:, rsa_key:)
+          @provider = provider
+          @issuer   = issuer
+          @audience = audience
+          @kid      = kid
+          @rsa_key  = rsa_key
+        end
+
+        # Produces a signed JWT. Only `sub:` is required; anything else
+        # (email, name, roles, exp, …) flows through as a claim override.
+        def sign(sub:, **overrides)
+          encode(default_claims(sub: sub).merge(overrides), kid: @kid)
+        end
+
+        def sign_expired(sub:, **overrides)
+          sign(sub: sub, exp: (Time.now.to_i - DEFAULT_TTL), **overrides)
+        end
+
+        def sign_wrong_audience(sub:, **overrides)
+          sign(sub: sub, aud: "wrong-aud", **overrides)
+        end
+
+        def sign_unknown_kid(sub:, **overrides)
+          encode(default_claims(sub: sub).merge(overrides), kid: "rogue-kid")
+        end
+
+        # Sign cleanly, then flip the last character so the signature no
+        # longer verifies. Result still parses as a JWT shape but verify fails.
+        def sign_tampered(sub:, **overrides)
+          token = sign(sub: sub, **overrides)
+          last  = token[-1]
+          token[0..-2] + (last == "A" ? "B" : "A")
+        end
+
+        private
+
+        def default_claims(sub:)
+          {
+            iss: @issuer,
+            sub: sub.to_s,
+            aud: @audience,
+            exp: (Time.now + DEFAULT_TTL).to_i,
+            iat: Time.now.to_i
+          }
+        end
+
+        def encode(claims, kid:)
+          jwt = JSON::JWT.new(claims)
+          jwt.kid = kid
+          jwt.sign(@rsa_key, :RS256).to_s
+        end
+      end
+    end
+  end
+end