keycloak-sdk 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ced74e5c197f31bcea44f678715d2c2b30d8cfe6b597393a200bda451057f582
-  data.tar.gz: ff1f1781cfc00acfcca781217eedb6be8f76c7efc72f93b49940f9a85882f1b2
+  metadata.gz: dc6cc81e7537b1962108102b160aaeb30e45d1018ac533f834204dd58c69af3f
+  data.tar.gz: 172f64d5db58105f0402ecbe1821ed2e2c2f2910139c75144b788c38fa170c5c
 SHA512:
-  metadata.gz: 2e4564e3f092dc1161a80e4bd0bb854dd1c05b4c57dd9552db23c8607f5aace485dc5fd160dddcae0e7c27989ddf4b0f4a889e6f365345dc847504afd61c4dea
-  data.tar.gz: 2b4df9762901e5b1c7f43372952a298ee82392a6ab95cabbfd974c737213813266d7c206dcea5ee5f3509330f71a6674edc8ae5017c77a6769783cedb5356e16
+  metadata.gz: 19f5d3264eaec1620a68a509bcfdfe5c7180a1e7bc90867f96ffce31901ce0670e06a80d8925655e4977a13f6e1675936e59e4920cd431087372c06a0725d05c
+  data.tar.gz: 1b534ae18c8a9e1cb7bbf492ccf9713bb9fee474afd0348d05b43b6c9cfd3e22fe773654c615f6e568609c3644603822a70330184d42fc97fb2133658fcaef89

data/README.md

@@ -4,7 +4,7 @@ Authentication (OIDC / OAuth2) and the Admin REST API for [Keycloak](https://www
 
 Part of a **nine-language polyglot SDK** (Java · Python · Node · Go · C# · PHP · Rust · Ruby · Kotlin) — one API surface, isomorphic across all of them: [github.com/xzawed/KeyCloakSDK](https://github.com/xzawed/KeyCloakSDK).
 
-> **`1.0.1` is on RubyGems** — a patch release of security and correctness fixes on top of `1.0.0`, the first release carrying the stability guarantee. A bare `gem install keycloak-sdk` resolves it. Admin path segments are now escaped (an unescaped name could redirect a call to another endpoint), the token provider's default `inspect` no longer prints the cached access token, a token whose expiry is unknown is treated as expired, JWKS responses are size-capped, an empty `200` JWKS key set no longer replaces a good cached one, failed JWKS fetches back off instead of hitting the IdP on every validation, and a token response of the wrong shape is no longer returned as a success. ⚠️ **A `server_url` that is not an absolute http(s) URL now raises `ConfigError` when the config is built**, instead of a stdlib exception on the first call.
+> **`1.1.0` is on RubyGems** — a minor release of security fixes on top of `1.0.1`; `1.0.0` was the first release carrying the stability guarantee. A bare `gem install keycloak-sdk` resolves it. An error raised on a malformed or hostile IdP response no longer prints that response or the secrets the SDK sent (present in `1.0.1`): `full_message` — what a logger prints — showed a non-JSON body's head, an echoed `error_description` and a broken status line, a lower `Faraday::ParsingError`'s `inspect` showed the request's client secret, refresh token and admin bearer, and on Ruby 3.2 an unwrapped `NoMethodError` quoted the response body. OAuth failures now carry only the error code (when it is shaped like one) and the HTTP status in their message, and a malformed `200` token response is an `AuthError`. **Added**: `KeycloakSdk::RedactedCause`. ⚠️ **An SDK error's `cause` is now a `KeycloakSdk::RedactedCause` — the lower class names (`lower_classes`) and the backtrace, no message — instead of the original Faraday, rack-oauth2 or JSON exception**, so a `rescue` or `is_a?` on `err.cause` against those types no longer matches. ⚠️ **A token or introspection response that is not a JSON object now raises `AuthError`** — an introspection body that was a string used to come back as a result.
 
 ## Requirements
 

data/lib/keycloak_sdk/admin/call.rb

@@ -32,7 +32,8 @@ module KeycloakSdk
 
         raise AdminError.from_status(resp.status, "admin request failed: HTTP #{resp.status}")
       rescue Faraday::Error => e
-        raise TransportError, "admin transport error: #{e.message}"
+        # 원본을 달면 `Faraday::ParsingError#inspect` 가 요청의 베어러 토큰을, 메시지가 응답 앞부분을 찍는다(실측).
+        raise TransportError, "admin transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
       end
 
       def id_from_location(resp)

data/lib/keycloak_sdk/auth_client.rb

@@ -11,6 +11,10 @@ module KeycloakSdk
   class AuthClient
     include TokenProvider
 
+    # 메시지에 실어도 되는 OAuth 오류 코드 모양 — RFC 6749·OIDC 등록 코드와 Keycloak 코드는 전부 이 모양이고,
+    # 토큰·시크릿(JWT·base64·hex·UUID)은 대문자·숫자·점·하이픈 때문에 걸러진다.
+    OAUTH_CODE = /\A[a-z_]{1,64}\z/
+
     def initialize(config:, http:, jwt_validator:)
       @config = config
       @http = http
@@ -41,31 +45,19 @@ module KeycloakSdk
     def exchange_code(code:, code_verifier:, redirect_uri:, expected_nonce: nil)
       client = oauth_client(redirect_uri: redirect_uri)
       client.authorization_code = code
-      token_set = to_token_set(client.access_token!(code_verifier: code_verifier))
+      token_set = token_request("authorization_code exchange") { client.access_token!(code_verifier: code_verifier) }
       verify_nonce!(token_set.id_token, expected_nonce) unless expected_nonce.nil?
       token_set
-    rescue Rack::OAuth2::Client::Error => e
-      raise AuthError.new("authorization_code exchange failed: #{e.message}", oauth_error: e.response[:error].to_s)
-    rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
     end
 
     def refresh(refresh_token:)
       client = oauth_client
       client.refresh_token = refresh_token
-      to_token_set(client.access_token!)
-    rescue Rack::OAuth2::Client::Error => e
-      raise AuthError.new("refresh failed: #{e.message}", oauth_error: e.response[:error].to_s)
-    rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
+      token_request("refresh") { client.access_token! }
     end
 
     def client_credentials_token
-      to_token_set(oauth_client.access_token!(scope: @config.scopes.join(" ")))
-    rescue Rack::OAuth2::Client::Error => e
-      raise AuthError.new("client-credentials failed: #{e.message}", oauth_error: e.response[:error].to_s)
-    rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
+      token_request("client-credentials") { oauth_client.access_token!(scope: @config.scopes.join(" ")) }
     end
 
     # TokenProvider 계약(직접 사용용). admin은 캐싱 provider를 별도로 쓴다.
@@ -81,7 +73,7 @@ module KeycloakSdk
 
       IntrospectionResult.from_response(resp.body)
     rescue Faraday::Error => e
-      raise TransportError, "introspection transport error: #{e.message}"
+      raise TransportError, "introspection transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
 
     def logout(refresh_token:)
@@ -93,7 +85,7 @@ module KeycloakSdk
 
       nil
     rescue Faraday::Error => e
-      raise TransportError, "logout transport error: #{e.message}"
+      raise TransportError, "logout transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
 
     def validate(token)
@@ -127,6 +119,27 @@ module KeycloakSdk
       raise AuthError, "authorization_code exchange failed: invalid id_token: #{e.message}"
     end
 
+    # rack-oauth2 토큰 호출의 오류 경계(§4). 하위 예외는 SDK 타입이 되고 `cause` 에는 원본 대신 `RedactedCause` 가 달린다.
+    # ⚠️ OAuth 오류는 **코드와 HTTP 상태만** 싣는다 — `error_description` 은 서버가 고른 자유 문장이라 토큰을
+    # 되울릴 수 있고, 오류 본문이 JSON 이 아니면 rack-oauth2 가 본문 전체를 거기 넣는다. 코드 자리도 서버 값이라
+    # **코드 모양**(`OAUTH_CODE` — 등록 코드는 전부 소문자·밑줄)일 때만 메시지에 싣는다(`oauth_error` 에는 그대로).
+    # ⚠️ 마지막 `StandardError` 는 rack-oauth2 가 형식이 틀린 200 을 읽다 내는 것(NoMethodError·AttrMissing·
+    # 'Unknown Token Type')과 `to_token_set` 의 형 변환 실패다 — 원본이 새면 Ruby 3.2 의 NoMethodError 가 본문을 인용한다.
+    def token_request(operation)
+      to_token_set(yield)
+    rescue Error
+      raise
+    rescue Rack::OAuth2::Client::Error => e
+      code = e.response[:error].is_a?(String) ? e.response[:error] : ""
+      shown = code.match?(OAUTH_CODE) ? code : "non-standard error code"
+      raise AuthError.new("#{operation} failed: #{shown} (HTTP #{e.status})", oauth_error: code),
+            cause: RedactedCause.new(e)
+    rescue Faraday::Error => e
+      raise TransportError, "token endpoint transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
+    rescue StandardError => e
+      raise AuthError, "#{operation} failed: unusable token response (#{e.class})", cause: RedactedCause.new(e)
+    end
+
     def oauth_client(redirect_uri: nil)
       Rack::OAuth2::Client.new(
         identifier: @config.client_id,
@@ -137,17 +150,19 @@ module KeycloakSdk
       )
     end
 
+    # `expires_in` 은 `TokenSet.from_response` 와 같이 정수로 읽는다(문자열 "300" 허용) — 예전에는 문자열이면
+    # `Float + String` 의 TypeError 가 경계를 뚫었다. 변환 실패는 `token_request` 가 AuthError 로 바꾼다.
     def to_token_set(token)
       raw = token.raw_attributes || {}
-      scope = raw[:scope] || raw["scope"]
+      expires_in = token.expires_in && Integer(token.expires_in)
       TokenSet.new(
         access_token: token.access_token,
         token_type: "Bearer",
-        expires_in: token.expires_in,
+        expires_in: expires_in,
         refresh_token: token.refresh_token,
         id_token: raw[:id_token] || raw["id_token"],
-        scope: scope,
-        expires_at: token.expires_in ? Time.now.to_f + token.expires_in : nil
+        scope: raw[:scope] || raw["scope"],
+        expires_at: expires_in ? Time.now.to_f + expires_in : nil
       )
     end
   end

data/lib/keycloak_sdk/errors.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "openssl"
+require "socket"
+require "timeout"
+
 module KeycloakSdk
   # 모든 SDK 오류의 루트.
   class Error < StandardError; end
@@ -46,4 +50,39 @@ module KeycloakSdk
   class NotFoundError < AdminError; end
   class ConflictError < AdminError; end
   class ForbiddenError < AdminError; end
+
+  # SDK 오류의 `cause` 에 원본 하위 예외 대신 다는 사본 — **클래스 이름 사슬과 백트레이스만** 옮긴다.
+  # 경계는 `raise …, cause: RedactedCause.new(e)` 로 단다(`KeycloakSdk::Error` 가 아니다 — 원인 자리에만 있다).
+  #
+  # ⚠️ Ruby 는 `rescue` 안의 `raise` 가 처리 중인 예외를 `cause` 에 **자동으로** 달고, `full_message`(잡히지 않은
+  # 예외·로거)가 그 사슬의 메시지를 찍는다. 하위 예외는 응답을 싣는다 — JSON 파서는 본문 앞 32 바이트를,
+  # rack-oauth2 는 `error_description`(JSON 이 아닌 오류면 본문 전체)을, Net::HTTP 는 깨진 상태 줄을 메시지에 싣고,
+  # `Faraday::ParsingError#inspect` 는 **요청** 본문·헤더(클라이언트 시크릿·refresh 토큰·베어러)까지 찍었다. Ruby 3.2 의
+  # `NoMethodError` 는 수신자(응답 본문)를 인용했다(실측 2026-09-26 · `spec/unit/hostile_token_response_spec.rb`).
+  # 원본 객체를 공개 API 로 내보내지 않는 것은 §4 도 요구한다.
+  class RedactedCause < StandardError
+    # 메시지를 SDK 메시지로 옮겨도 되는 하위 원인 — 응답을 인용할 수 없는 소켓·타임아웃·TLS 실패뿐이다.
+    # ⚠️ `Faraday::ConnectionFailed` 를 통째로 넣지 않는다 — `Net::HTTPBadResponse`(깨진 상태 줄 dump)도 그것으로 온다.
+    QUOTE_FREE = [SystemCallError, SocketError, IOError, Timeout::Error, OpenSSL::SSL::SSLError].freeze
+
+    # 원본과 그 `cause` 들의 클래스 이름(바깥부터).
+    attr_reader :lower_classes
+
+    def initialize(error)
+      @lower_classes = []
+      link = error
+      while link && @lower_classes.size < 8
+        @lower_classes << link.class.name
+        link = link.cause
+      end
+      super("#{@lower_classes.join(' <- ')} (message withheld: it can quote the response)")
+      set_backtrace(error.backtrace) if error.backtrace
+    end
+
+    # SDK 메시지에 실을 하위 오류 설명 — 인용할 수 없는 연결 실패면 그 메시지, 아니면 클래스 이름뿐.
+    def self.describe(error)
+      origin = error.respond_to?(:wrapped_exception) && error.wrapped_exception ? error.wrapped_exception : error
+      QUOTE_FREE.any? { |k| origin.is_a?(k) } ? error.message : error.class.name
+    end
+  end
 end

data/lib/keycloak_sdk/jwks_store.rb

@@ -122,11 +122,11 @@ module KeycloakSdk
       body = begin
         JSON.parse(buf)
       rescue JSON::ParserError => e
-        raise TransportError, "JWKS response unparsable: #{e.message}"
+        raise TransportError, "JWKS response unparsable (JSON::ParserError)", cause: RedactedCause.new(e)
       end
       validate_key_set!(body)
     rescue Faraday::Error => e
-      raise TransportError, "JWKS transport error: #{e.message}"
+      raise TransportError, "JWKS transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
 
     # 파싱된 본문이 **캐시에 올려도 되는 집합인가**. 통과하면 그 본문을 돌려준다.

data/lib/keycloak_sdk/jwt_validator.rb

@@ -34,7 +34,9 @@ module KeycloakSdk
       payload, = JWT.decode(token, nil, true, decode_options)
       to_validated(payload)
     rescue JWT::DecodeError => e
-      raise TokenValidationError, "JWT validation failed: #{e.message}"
+      # ruby-jwt 메시지는 입력을 인용하지 않는다. 그 **원인**은 인용한다 — 조각이 JSON 이 아니면 JSON::ParserError 가
+      # 디코드한 토큰 조각을 싣는다(실측) — 그래서 사슬은 `RedactedCause` 로 끊는다.
+      raise TokenValidationError, "JWT validation failed: #{e.message}", cause: RedactedCause.new(e)
     end
 
     private

data/lib/keycloak_sdk/token_provider.rb

@@ -59,7 +59,7 @@ module KeycloakSdk
 
       TokenSet.from_response(resp.body, received_at: Time.now.to_f)
     rescue Faraday::Error => e
-      raise TransportError, "token endpoint transport error: #{e.message}"
+      raise TransportError, "token endpoint transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
   end
 end

data/lib/keycloak_sdk/tokens.rb

@@ -17,6 +17,9 @@ module KeycloakSdk
     end
 
     def self.from_response(body, received_at: Time.now.to_f)
+      # 배열 본문은 `Array#[]` 의 TypeError 로 경계를 뚫었다 — 객체가 아니면 SDK 오류다.
+      raise AuthError, "token response is not a JSON object" unless body.is_a?(Hash)
+
       # ⚠️ **존재 검사는 타입 검사가 아니다.** 예전에는 값을 그대로 담아 숫자·해시·nil 이
       # `access_token` 이 됐고, 소비자는 그것을 Bearer 로 실어 보내 매번 401 을 받았다
       # (조용한 반복 실패). `expires_in` 의 문자열 허용은 **의도된 것**이라 건드리지 않는다.
@@ -25,7 +28,12 @@ module KeycloakSdk
         raise AuthError, "token response has no usable access_token"
       end
 
-      expires_in = body["expires_in"] && Integer(body["expires_in"])
+      expires_in = begin
+        body["expires_in"] && Integer(body["expires_in"])
+      rescue ArgumentError, TypeError, RangeError # RangeError: JSON 1e400 = Infinity → FloatDomainError
+        # `cause: nil` — ArgumentError 는 그 값을 인용한다(`invalid value for Integer(): "…"`).
+        raise AuthError, "token response has an unusable expires_in", cause: nil
+      end
       new(
         access_token: access_token,
         token_type: body["token_type"],
@@ -67,7 +75,10 @@ module KeycloakSdk
 
   # RFC 7662 introspection 결과.
   IntrospectionResult = Data.define(:active, :username, :client_id, :claims) do
+    # 객체가 아닌 본문은 SDK 오류다 — 배열은 TypeError 로 경계를 뚫었고, 문자열은 `claims` 가 문자열인 결과가 됐다.
     def self.from_response(body)
+      raise AuthError, "introspection response is not a JSON object" unless body.is_a?(Hash)
+
       new(active: body["active"] == true, username: body["username"],
           client_id: body["client_id"], claims: body)
     end

data/lib/keycloak_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeycloakSdk
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keycloak-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - xzawed