keycloak-sdk 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39cf848bf3f01443707855e1a981e8bcaf4fdbb3a5ac9fbf17a7b6ac010e33f4
-  data.tar.gz: 489cfcf03654e7da757bfcd6020cf148d3fb9550c89ea9f14c09569977aa47b8
+  metadata.gz: dc6cc81e7537b1962108102b160aaeb30e45d1018ac533f834204dd58c69af3f
+  data.tar.gz: 172f64d5db58105f0402ecbe1821ed2e2c2f2910139c75144b788c38fa170c5c
 SHA512:
-  metadata.gz: a2c51c7d06751f6ae0c6ed76d83083400f679354a011d1dbc720c93fd374cf1047092c4dc8214931ea8f25fd2a6099e5103577c35aee998194e0c56b7645c9fb
-  data.tar.gz: 3d112a01d129df0a1bbebb7ef3b0ba75b4947fd5bb1014a7471beef728f2d22be9020d264f98660d887f1820e58e6014caa4bf12cd0dc8787571568b4c320a56
+  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.0` is on RubyGems** — the first release carrying the stability guarantee. A bare `gem install keycloak-sdk` resolves it.
+> **`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
 
@@ -64,8 +64,8 @@ The five admin resources — `users` / `clients` / `roles` / `groups` / `realms`
 The SDK replaces the unsafe library defaults rather than inheriting them:
 
 - **Algorithm pinning** — the header-supplied `alg` is never trusted, so `alg: none` and HS/RS confusion are rejected structurally: the pin is applied before key lookup and signature verification, not after.
-- **Strict claim checks** — exact `iss` match, `aud` containment, mandatory `exp`, `nbf`, and a bounded clock skew.
-- **DoS-safe JWKS** — a refetch is triggered only by an unresolved key ID and never by a bad signature, and is rate-limited to a minimum interval (`jwks_min_refetch`, 30s by default). The gate applies on a cold cache too, so it cannot be sidestepped by hitting the SDK before its first successful fetch — no volume of forged tokens makes the SDK issue more than one JWKS request per interval.
+- **Strict claim checks** — exact `iss` match, `aud` containment, mandatory `exp`, `nbf` enforced when present, and a bounded clock skew.
+- **DoS-safe JWKS** — a refetch is triggered only by an unresolved key ID and never by a bad signature, and is rate-limited to a minimum interval (`jwks_min_refetch`, 30s by default) — so **once the key set has been fetched**, no volume of forged tokens makes the SDK issue more than one JWKS request per interval. A *failed* fetch is bounded separately: consecutive failures back off exponentially (0.2s, doubling, capped at 5s, with jitter), and inside that window the SDK **fails fast without contacting the IdP**. So a cold cache during an IdP outage no longer turns every validation into a request (measured: 20 attempts → 1 request, down from 20). ⚠️ The SDK never sleeps — it returns the error immediately, so retry pacing stays the caller's decision.
 - **OIDC nonce / `id_token` replay protection** — `create_authorization_request` always issues a nonce (same default as `state:`) and puts it on the authorization URL. Pass it back as `exchange_code(expected_nonce:)` and the SDK fully validates the `id_token` before comparing the nonce claim. Omit `expected_nonce:` and id_token validation is skipped (same opt-out as the other eight languages).
 - **Secret handling** — `Config`, `TokenSet`, and `AuthorizationRequest` mask secrets and tokens in `#inspect` (`***`, no prefix leak), TLS verification is on by default, timeouts are always applied, and redirect-following middleware is never installed (SSRF hardening).
 
@@ -73,11 +73,11 @@ Masking covers this SDK's own `#inspect`; it cannot cover what your logging fram
 
 ## Versioning and support
 
-This SDK is **`1.0`** and follows SemVer: a breaking change to the public API requires a **major** bump. That promise is machine-backed — CI diffs this lane's public API against the **previously published artifact** on every build (`yard diff`), and a removal or an incompatible change fails the build. ⚠️ **This lane’s gate is narrower than its siblings’**: Ruby has no equivalent of `japicmp`/`gorelease`, so the gate catches a **removed** public object but not a changed method signature — that case is caught by review, not by machine. ⚠️ **The gate compares the API _surface_.** A change that leaves the surface identical but alters behaviour is not caught by it, so read the release notes before upgrading.
+This SDK is **`1.0`** and follows SemVer: a breaking change to the public API requires a **major** bump. That promise is machine-backed — CI diffs this lane's public API against the **previously published artifact** on every build (`yard diff`), and a removal fails the build. ⚠️ **This lane’s gate is narrower than its siblings’**: Ruby has no equivalent of `japicmp`/`gorelease`, so the gate catches a **removed** public object but not a changed method signature — that case is caught by review, not by machine. ⚠️ **The gate compares the API _surface_.** A change that leaves the surface identical but alters behaviour is not caught by it, so read the release notes before upgrading.
 
 Only the newest released version of each language SDK receives security fixes; there are no long-term-support lines and older releases are not backported to.
 
-**Each of the nine languages versions independently.** All nine reached `1.0.0` on the same day because they earned the same guarantee at the same time — they do **not** move in lockstep afterwards.
+**Each of the nine languages versions independently.** All nine reached `1.0.0` in the same release wave because they earned the same guarantee at the same time — they do **not** move in lockstep afterwards.
 
 ## Documentation
 

data/lib/keycloak_sdk/admin/call.rb

@@ -1,18 +1,39 @@
 # frozen_string_literal: true
 
+require "erb"
+
 module KeycloakSdk
   module Admin
-    # 리소스 공용: 요청 실행 + 오류 경계 변환 + Location 헤더 id 추출.
+    # 리소스 공용: 요청 실행 + 오류 경계 변환 + Location 헤더 id 추출 + 경로 세그먼트 이스케이프.
     module Call
       private
 
+      # 경로 세그먼트 하나를 이스케이프한다. **모든 admin 리소스가 이것을 거쳐야 한다.**
+      #
+      # 날 문자열 보간은 두 가지를 깬다:
+      #  (1) "../" 를 담은 값이 경로를 재작성한다 — Faraday 가 base_url 기준으로 정규화하므로
+      #      `users/../../../foo` 가 `/admin/foo` 로 접히고, 서비스 계정 베어러를 실은 채
+      #      의도하지 않은 엔드포인트로 간다.
+      #  (2) Keycloak 이 허용하는 **공백 든 role/group 이름**이 `URI::InvalidURIError` 를 올린다.
+      #      그것은 `Faraday::Error` 가 아니라 stdlib 예외라 `request` 의 rescue 를 통과해
+      #      §4「하위 오류는 경계에서 SDK 타입으로 변환된다」까지 함께 깬다.
+      #
+      # `ERB::Util.url_encode` 는 unreserved(A-Za-z0-9\-_.~) 밖을 전부 퍼센트 인코딩하고
+      # 공백을 `+` 가 아니라 `%20` 으로 낸다 — 경로 세그먼트에 맞는 유일한 stdlib 선택지다
+      # (`CGI.escape` 는 공백을 `+` 로 내므로 경로에서 틀린다). Go 의 `url.PathEscape` 와
+      # 같은 자리를 채우며, 그 참조 구현이 `go/admin_realms.go` 에 있다.
+      def esc(segment)
+        ERB::Util.url_encode(segment.to_s)
+      end
+
       def request
         resp = yield
         return resp if resp.success?
 
         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/admin/clients.rb

@@ -11,25 +11,25 @@ module KeycloakSdk
       end
 
       def create(representation)
-        id_from_location(request { @conn.post("admin/realms/#{@realm}/clients", representation) })
+        id_from_location(request { @conn.post("admin/realms/#{esc(@realm)}/clients", representation) })
       end
 
       def get(id)
-        request { @conn.get("admin/realms/#{@realm}/clients/#{id}") }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/clients/#{esc(id)}") }.body
       end
 
       # client_id로 조회: 목록 + 필터(admin은 내부 uuid 키).
       def list(**params)
-        request { @conn.get("admin/realms/#{@realm}/clients", params) }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/clients", params) }.body
       end
 
       def update(id, representation)
-        request { @conn.put("admin/realms/#{@realm}/clients/#{id}", representation) }
+        request { @conn.put("admin/realms/#{esc(@realm)}/clients/#{esc(id)}", representation) }
         nil
       end
 
       def delete(id)
-        request { @conn.delete("admin/realms/#{@realm}/clients/#{id}") }
+        request { @conn.delete("admin/realms/#{esc(@realm)}/clients/#{esc(id)}") }
         nil
       end
     end

data/lib/keycloak_sdk/admin/groups.rb

@@ -11,24 +11,24 @@ module KeycloakSdk
       end
 
       def create(representation)
-        id_from_location(request { @conn.post("admin/realms/#{@realm}/groups", representation) })
+        id_from_location(request { @conn.post("admin/realms/#{esc(@realm)}/groups", representation) })
       end
 
       def get(id)
-        request { @conn.get("admin/realms/#{@realm}/groups/#{id}") }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/groups/#{esc(id)}") }.body
       end
 
       def list(**params)
-        request { @conn.get("admin/realms/#{@realm}/groups", params) }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/groups", params) }.body
       end
 
       def update(id, representation)
-        request { @conn.put("admin/realms/#{@realm}/groups/#{id}", representation) }
+        request { @conn.put("admin/realms/#{esc(@realm)}/groups/#{esc(id)}", representation) }
         nil
       end
 
       def delete(id)
-        request { @conn.delete("admin/realms/#{@realm}/groups/#{id}") }
+        request { @conn.delete("admin/realms/#{esc(@realm)}/groups/#{esc(id)}") }
         nil
       end
     end

data/lib/keycloak_sdk/admin/realms.rb

@@ -17,7 +17,7 @@ module KeycloakSdk
       end
 
       def get(realm)
-        request { @conn.get("admin/realms/#{realm}") }.body
+        request { @conn.get("admin/realms/#{esc(realm)}") }.body
       end
 
       def list
@@ -25,12 +25,12 @@ module KeycloakSdk
       end
 
       def update(realm, representation)
-        request { @conn.put("admin/realms/#{realm}", representation) }
+        request { @conn.put("admin/realms/#{esc(realm)}", representation) }
         nil
       end
 
       def delete(realm)
-        request { @conn.delete("admin/realms/#{realm}") }
+        request { @conn.delete("admin/realms/#{esc(realm)}") }
         nil
       end
     end

data/lib/keycloak_sdk/admin/roles.rb

@@ -11,24 +11,24 @@ module KeycloakSdk
       end
 
       def create(representation)
-        id_from_location(request { @conn.post("admin/realms/#{@realm}/roles", representation) })
+        id_from_location(request { @conn.post("admin/realms/#{esc(@realm)}/roles", representation) })
       end
 
       def get(name)
-        request { @conn.get("admin/realms/#{@realm}/roles/#{name}") }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/roles/#{esc(name)}") }.body
       end
 
       def list(**params)
-        request { @conn.get("admin/realms/#{@realm}/roles", params) }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/roles", params) }.body
       end
 
       def update(name, representation)
-        request { @conn.put("admin/realms/#{@realm}/roles/#{name}", representation) }
+        request { @conn.put("admin/realms/#{esc(@realm)}/roles/#{esc(name)}", representation) }
         nil
       end
 
       def delete(name)
-        request { @conn.delete("admin/realms/#{@realm}/roles/#{name}") }
+        request { @conn.delete("admin/realms/#{esc(@realm)}/roles/#{esc(name)}") }
         nil
       end
     end

data/lib/keycloak_sdk/admin/users.rb

@@ -11,24 +11,24 @@ module KeycloakSdk
       end
 
       def create(representation)
-        id_from_location(request { @conn.post("admin/realms/#{@realm}/users", representation) })
+        id_from_location(request { @conn.post("admin/realms/#{esc(@realm)}/users", representation) })
       end
 
       def get(id)
-        request { @conn.get("admin/realms/#{@realm}/users/#{id}") }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/users/#{esc(id)}") }.body
       end
 
       def list(**params)
-        request { @conn.get("admin/realms/#{@realm}/users", params) }.body
+        request { @conn.get("admin/realms/#{esc(@realm)}/users", params) }.body
       end
 
       def update(id, representation)
-        request { @conn.put("admin/realms/#{@realm}/users/#{id}", representation) }
+        request { @conn.put("admin/realms/#{esc(@realm)}/users/#{esc(id)}", representation) }
         nil
       end
 
       def delete(id)
-        request { @conn.delete("admin/realms/#{@realm}/users/#{id}") }
+        request { @conn.delete("admin/realms/#{esc(@realm)}/users/#{esc(id)}") }
         nil
       end
     end

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/config.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "uri"
+
 module KeycloakSdk
   # 불변 설정. 생성 시 검증하고 freeze한다. client_secret은 inspect에서 마스킹.
   class Config
@@ -19,6 +21,10 @@ module KeycloakSdk
     # 않았으나 JWKS가 10.0/30.0으로 갈린 것과 똑같은 모양이다). 그 자리는 이제 이 상수를 참조한다.
     DEFAULT_CLOCK_SKEW = 30
 
+    # 깨진 server_url의 ConfigError 접두사. 뒤에 짧은 사유만 붙인다(입력·파서 메시지 금지).
+    SERVER_URL_ERROR_PREFIX = "server_url must be an absolute http(s) URL: "
+    private_constant :SERVER_URL_ERROR_PREFIX
+
     attr_reader :server_url, :realm, :client_id, :client_secret,
                 :scopes, :signature_algorithms, :connect_timeout, :read_timeout, :clock_skew,
                 :jwks_min_refetch, :expected_audience
@@ -28,6 +34,11 @@ module KeycloakSdk
                    connect_timeout: 10, read_timeout: 10, clock_skew: DEFAULT_CLOCK_SKEW,
                    jwks_min_refetch: DEFAULT_JWKS_MIN_REFETCH, expected_audience: nil)
       @server_url = strip_trailing_slashes(normalize_required("server_url", server_url))
+      # 정규화 직후. 상대 URL("kc.example.com")은 첫 토큰 요청에서 RuntimeError "No Host Info"로,
+      # 공백이 섞인 URL("http://kc example.com")은 URI::InvalidURIError로 나간다. 둘 다
+      # ConfigError가 아니라 공개 API 밖으로 새는 예외라 생성 시점에 닫는다.
+      # InvalidURIError#message는 입력을 그대로 에코하므로 사유만 남긴다.
+      require_absolute_http_url!(@server_url)
       @realm = normalize_required("realm", realm)
       @client_id = normalize_required("client_id", client_id)
       @client_secret = client_secret
@@ -67,6 +78,19 @@ module KeycloakSdk
       str[0, i]
     end
 
+    # URI::HTTP(HTTPS는 하위 클래스)이고 host가 비어 있지 않으며 port <= 65535.
+    # 스킴 대소문자는 URI.parse가 가린다("HTTP://" → URI::HTTP). 언더스코어 host
+    # ("keycloak_server")도 이 파서가 받으므로 따로 거부하지 않는다.
+    def require_absolute_http_url!(url)
+      uri = URI.parse(url)
+      raise ConfigError, "#{SERVER_URL_ERROR_PREFIX}scheme must be http or https" unless uri.is_a?(URI::HTTP)
+      raise ConfigError, "#{SERVER_URL_ERROR_PREFIX}missing host" if uri.host.to_s.empty?
+      raise ConfigError, "#{SERVER_URL_ERROR_PREFIX}port out of range" if uri.port > 65_535
+    rescue URI::InvalidURIError
+      # cause를 끊지 않으면 InvalidURIError#message(입력 에코)가 예외 사슬에 남는다.
+      raise ConfigError, "#{SERVER_URL_ERROR_PREFIX}unparseable", cause: nil
+    end
+
     def normalize_required(name, value)
       raise ConfigError, "#{name} is required" if value.nil?
 

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "json" # ⚠️ `on_data` 를 쓰면 json 미들웨어가 돌지 않아 여기서 직접 파싱한다
 
 module KeycloakSdk
   # DoS-safe JWKS 스토어. Mutex 캐시 + rate-limit + single-flight.
@@ -8,6 +9,27 @@ module KeycloakSdk
   # 미해결 kid(force:true)만 재조회하며, rate-limit gate는 재조회 결정 시점에 stamp한다
   # (성공 아님 — IdP 장애창에서 위조 kid 폭주에도 재조회를 상한한다). Go/Rust/Python 동형.
   class JwksStore
+    # ⚠️ **실패한 fetch 의 백오프 — `min_refetch` 와 다른 축이다.**
+    # `min_refetch`(30초)는 *캐시가 찬 뒤* 미해결 kid 홍수를 막는다. 아래 둘은 **캐시가 비어
+    # 있고 fetch 가 계속 실패할 때**를 막는다. 그 자리에는 게이트가 없어서, 측정상 20회 검증이
+    # IdP 요청 20건을 그대로 냈다(2026-09-04 · 7개 언어 동일).
+    #
+    # ⚠️ **여기에 `min_refetch`(30초)를 재사용하면 안 된다** — 일시적 503 한 번이 「30초간 어떤
+    # 토큰도 검증 불가」가 된다. 그래서 짧게 시작해 지수적으로 늘리고 상한을 둔다.
+    #
+    # ⚠️ **sleep 하지 않는다.** 라이브러리가 호출자의 스레드를 붙잡으면 안 되므로, 백오프 창
+    # 안에서는 **IdP 를 때리지 않고 즉시 실패**시킨다(negative cache). 재시도 정책은 소비자 몫이다.
+    FAILURE_BACKOFF_BASE = 0.2 # 초 — 첫 실패 후 대기
+    FAILURE_BACKOFF_CAP  = 5.0 # 초 — 지수 증가의 상한
+
+    # ⚠️ **본문을 통째로 읽기 전에 상한을 건다.** 예전에는 `resp.body`(json 미들웨어가 이미
+    # 파싱한 값)를 그대로 받아 서버가 보내는 만큼 다 받았다 — 손상된 IdP 하나가 검증 경로를
+    # 메모리로 죽일 수 있었다. 51200 은 Nimbus `RemoteJWKSet.DEFAULT_HTTP_SIZE_LIMIT` 이고
+    # go(`jwksMaxBytes`)·rust(`JWKS_MAX_BYTES`)·java·kotlin 이 같은 수를 쓴다.
+    # ⚠️ `Content-Length` 로만 판정하면 그 헤더가 없거나 거짓인 응답을 놓친다 — 청크를 받으며
+    # 누적치가 상한을 넘는 순간 읽기를 끊는다(`on_data` 안에서 raise 하면 어댑터가 중단한다).
+    JWKS_MAX_BYTES = 51_200
+
     # ⚠️ 기본값을 여기 숫자로 적지 말 것 — `Config`가 유일한 정의 자리다. 이 클래스는 평범한
     # public 클래스라 소비자가 파사드를 거치지 않고 직접 생성할 수 있고, 예전에는 그 경로가
     # 문서의 30초가 아니라 10초를 받아 IdP를 3배 자주 때렸다(2026-08-13 Task D1).
@@ -18,6 +40,8 @@ module KeycloakSdk
       @mutex = Mutex.new
       @cache = nil        # {"keys" => [...]}
       @last_refetch = nil # monotonic seconds
+      @last_failure = nil # monotonic seconds — 마지막 fetch 실패 시각
+      @failures = 0       # 연속 실패 횟수(성공 시 0으로 되돌린다)
     end
 
     # ruby-jwt jwks: 로더가 호출. force=true는 미해결 kid 재조회 요청.
@@ -26,8 +50,16 @@ module KeycloakSdk
         return @cache if @cache && !force
         return @cache if force && !refetch_allowed?
 
+        # ⚠️ 백오프 검사는 fetch **직전**이자 30초 게이트 **이후**다. 콜드 캐시에서는 위 두 return
+        # 이 모두 통과하므로, 이 줄이 없으면 매 검증이 IdP 로 나간다(그게 원래 결함이다).
+        if backing_off?
+          raise TransportError,
+                "JWKS fetch backing off after #{@failures} consecutive failures " \
+                "(retry in #{backoff_remaining.round(2)}s)"
+        end
+
         @last_refetch = monotonic if force # 결정 시점 stamp(cold load는 예산 미소모)
-        @cache = fetch
+        @cache = fetch_recording_failure
       end
     end
 
@@ -37,16 +69,80 @@ module KeycloakSdk
       @last_refetch.nil? || (monotonic - @last_refetch) >= @min_refetch
     end
 
+    def backing_off?
+      backoff_remaining.positive?
+    end
+
+    def backoff_remaining
+      return 0.0 if @last_failure.nil?
+
+      backoff_delay - (monotonic - @last_failure)
+    end
+
+    # 지수 백오프 + jitter. jitter 는 [0.5, 1.0) 배수 — 여러 인스턴스가 같은 순간에 복구를
+    # 시도해 IdP 를 다시 무너뜨리는 것(thundering herd)을 흩는다.
+    #
+    # ⚠️ **PRNG API 를 쓰지 않고 나노초 시계에서 뽑는다.** 이 값은 비밀이 아니지만, 보안 민감
+    # 코드에서 약한 PRNG 를 호출하면 정적분석이 정당하게 막는다(실측: sonar S2245 · gosec G404).
+    # 일곱 언어가 **같은 관용**을 쓴다 — 하나만 `rand` 로 남으면 그 자체가 드리프트다.
+    def backoff_delay
+      raw = FAILURE_BACKOFF_BASE * (2**([@failures, 1].max - 1))
+      [raw, FAILURE_BACKOFF_CAP].min * jitter
+    end
+
+    def jitter
+      0.5 + ((Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) % 1_000_000) / 2_000_000.0)
+    end
+
+    def fetch_recording_failure
+      body = fetch
+      @failures = 0
+      @last_failure = nil
+      body
+    rescue StandardError
+      @failures += 1
+      @last_failure = monotonic
+      raise
+    end
+
     def fetch
-      resp = @http.get(@jwks_url)
+      # ⚠️ 상한은 **상태와 무관하게** 건다. 200 만 겨누면 오류 응답의 거대 본문이 그대로
+      # 들어온다 — php 가 정확히 그 순서였다(상태 검사 전에 `json_decode`).
+      buf = +""
+      resp = @http.get(@jwks_url) do |req|
+        req.options.on_data = proc do |chunk, _received|
+          buf << chunk
+          raise TransportError, "JWKS response exceeds #{JWKS_MAX_BYTES} bytes" if buf.bytesize > JWKS_MAX_BYTES
+        end
+      end
       raise TransportError, "JWKS fetch failed: HTTP #{resp.status}" unless resp.success?
 
-      body = resp.body
+      # ⚠️ `on_data` 를 쓰면 Faraday 는 본문을 누적하지 않으므로 json 미들웨어가 돌지 않는다 —
+      # 파싱은 여기서 한다. 파싱 실패도 경계에서 SDK 타입이 되어야 한다(§4).
+      body = begin
+        JSON.parse(buf)
+      rescue JSON::ParserError => e
+        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: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
+    end
+
+    # 파싱된 본문이 **캐시에 올려도 되는 집합인가**. 통과하면 그 본문을 돌려준다.
+    #
+    # ⚠️ **빈 집합은 정상 답이 아니고, 설치하면 검증기가 눈이 먼다**(go/jwt.go 와 동형 — 그쪽
+    # #380 픽스의 나머지 절반이다). `[]` 는 Array 라 malformed 검사를 그대로 통과한다.
+    # 200 + `{"keys":[]}` 를 주는 것은 키를 전부 회수한 IdP 가 아니라 프록시·WAF·반쯤 뜬
+    # realm 이고, 좋은 캐시를 그것으로 덮으면 방금 검증되던 토큰이 거부되며 refetch 게이트가
+    # 복구까지 막는다. 그래서 쓰기 **전에** 거부한다.
+    #
+    # ⚠️ 여기서 멈춘다 — `kty`·`n`·`e` 같은 필드 검증으로 번지면 JWKS 스키마 검사가 된다.
+    def validate_key_set!(body)
       raise TransportError, "JWKS response malformed" unless body.is_a?(Hash) && body["keys"].is_a?(Array)
+      raise TransportError, "JWKS response contains no keys" if body["keys"].empty?
 
       body
-    rescue Faraday::Error => e
-      raise TransportError, "JWKS transport error: #{e.message}"
     end
 
     def monotonic

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/oidc_endpoints.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
+require "erb"
+
 module KeycloakSdk
   # Keycloak realm의 OIDC 엔드포인트를 규약대로 조립한다(네트워크 없음).
   class OidcEndpoints
     attr_reader :issuer, :authorization, :token, :introspection, :end_session, :jwks
 
     def initialize(server_url, realm)
-      base = "#{server_url}/realms/#{realm}"
-      oidc = "#{base}/protocol/openid-connect"
-      @issuer = base
+      # issuer는 토큰 iss 클레임과 그대로 비교하므로 realm을 인코딩하지 않는다.
+      @issuer = "#{server_url}/realms/#{realm}"
+      # 엔드포인트의 realm은 경로 세그먼트 하나다. "my realm"을 그대로 두면
+      # client_credentials_token / create_authorization_request가 URI::InvalidURIError를
+      # SDK 밖으로 흘린다(자매 SDK는 이 세그먼트를 퍼센트 인코딩한다).
+      oidc = "#{server_url}/realms/#{escape_realm_segment(realm)}/protocol/openid-connect"
       @authorization = "#{oidc}/auth"
       @token = "#{oidc}/token"
       @introspection = "#{oidc}/token/introspect"
@@ -20,5 +25,13 @@ module KeycloakSdk
     def self.from_config(config)
       new(config.server_url, config.realm)
     end
+
+    private
+
+    # admin `esc`와 같은 stdlib 인코더. unreserved(A-Za-z0-9\-_.~)만 남기고 나머지
+    # UTF-8 바이트는 %XX(대문자). CGI.escape는 공백을 `+`로 내므로 경로 세그먼트에 못 쓴다.
+    def escape_realm_segment(realm)
+      ERB::Util.url_encode(realm.to_s)
+    end
   end
 end

data/lib/keycloak_sdk/token_provider.rb

@@ -20,6 +20,17 @@ module KeycloakSdk
       @expires_at = 0.0
     end
 
+    # ⚠️ 기본 `inspect` 는 인스턴스 변수를 전부 찍는데, 이 클래스는 **원시 액세스 토큰 문자열**을
+    # `@cached` 에 들고 있다(`ts.access_token` — TokenSet 이 아니라서 `TokenSet#inspect` 가 안 탄다).
+    # 실측(2026-09-12): 재정의 전 `p provider` 가 `@cached="AT-CENSUS-TOKEN-…"` 를 원문으로 찍었다.
+    # `Config`·`TokenSet` 은 재정의가 있는데 이 타입만 없어 생긴 **형제 간 불일치**였다.
+    # ⚠️ 캐시 유무는 남긴다 — 빈 캐시에 `***` 를 찍으면 「토큰이 있다」는 거짓 신호가 된다.
+    def inspect
+      "#<KeycloakSdk::ClientCredentialsTokenProvider config=#{@config.inspect} " \
+        "cached=#{@cached ? '"***"' : 'nil'} expires_at=#{@expires_at.inspect}>"
+    end
+    alias to_s inspect
+
     def access_token
       @mutex.synchronize do
         now = Time.now.to_f
@@ -48,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

@@ -4,10 +4,38 @@ module KeycloakSdk
   # OAuth 토큰 응답의 불변 값타입. access/refresh/id 토큰은 inspect에서 마스킹.
   TokenSet = Data.define(:access_token, :token_type, :expires_in, :refresh_token,
                          :id_token, :scope, :expires_at) do
+    # ⚠️ **검증은 팩토리가 아니라 생성자에 있다.** `from_response` 에만 두면 `AuthClient`
+    # 가 `TokenSet.new` 을 직접 부르는 경로(`auth_client.rb` 의 `to_token_set`)가 그것을
+    # 통째로 우회한다 — 독립 레그가 그 구멍을 지목했다. 생성자는 어떤 경로도 지나므로
+    # 여기 두면 우회가 불가능하다.
+    def initialize(access_token:, **rest)
+      unless access_token.is_a?(String) && !access_token.empty?
+        raise AuthError, "token response has no usable access_token"
+      end
+
+      super
+    end
+
     def self.from_response(body, received_at: Time.now.to_f)
-      expires_in = body["expires_in"] && Integer(body["expires_in"])
+      # 배열 본문은 `Array#[]` 의 TypeError 로 경계를 뚫었다 — 객체가 아니면 SDK 오류다.
+      raise AuthError, "token response is not a JSON object" unless body.is_a?(Hash)
+
+      # ⚠️ **존재 검사는 타입 검사가 아니다.** 예전에는 값을 그대로 담아 숫자·해시·nil 이
+      # `access_token` 이 됐고, 소비자는 그것을 Bearer 로 실어 보내 매번 401 을 받았다
+      # (조용한 반복 실패). `expires_in` 의 문자열 허용은 **의도된 것**이라 건드리지 않는다.
+      access_token = body["access_token"]
+      unless access_token.is_a?(String) && !access_token.empty?
+        raise AuthError, "token response has no usable access_token"
+      end
+
+      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: body["access_token"],
+        access_token: access_token,
         token_type: body["token_type"],
         expires_in: expires_in,
         refresh_token: body["refresh_token"],
@@ -17,8 +45,12 @@ module KeycloakSdk
       )
     end
 
+    # ⚠️ **만료 시각을 모르면 "만료됨"이다**(fail-safe — 자매 여덟과 동형, Java 의 M.6).
+    # `false`(=아직 살아있다)를 돌려주면 만료 시각 미상인 토큰이 **영원히 유효**해진다.
+    # `expires_at` 이 nil 인 경우는 서버가 `expires_in` 을 안 보냈을 때뿐이라 정상 경로가
+    # 아니고, 그때 취할 안전한 쪽은 "재발급"이다.
     def expired?(skew: 0, now: Time.now.to_f)
-      return false if expires_at.nil?
+      return true if expires_at.nil?
 
       now >= (expires_at - skew)
     end
@@ -29,6 +61,13 @@ module KeycloakSdk
         "id_token=#{id_token ? '"***"' : 'nil'} scope=#{scope.inspect} expires_at=#{expires_at.inspect}>"
     end
     alias_method :to_s, :inspect
+
+    # ⚠️ `pp`/`pretty_inspect` 는 `inspect` 와 같은 계급의 **표시 경로**인데, `Data` 타입은 PP 가
+    # 멤버를 직접 찍어 위 `inspect` 를 **건너뛴다**(실측: access_token 원문이 나왔다). 일반
+    # 클래스인 `Config` 는 PP 가 `inspect` 로 폴백해 안전하다 — 그래서 `Data` 만 이 훅이 필요하다.
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
   end
 
   # 검증된 access token의 관심 클레임.
@@ -36,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
@@ -54,5 +96,12 @@ module KeycloakSdk
         "nonce=#{nonce.inspect} code_verifier=\"***\">"
     end
     alias_method :to_s, :inspect
+
+    # ⚠️ `pp`/`pretty_inspect` 는 `inspect` 와 같은 계급의 **표시 경로**인데, `Data` 타입은 PP 가
+    # 멤버를 직접 찍어 위 `inspect` 를 **건너뛴다**(실측: access_token 원문이 나왔다). 일반
+    # 클래스인 `Config` 는 PP 가 `inspect` 로 폴백해 안전하다 — 그래서 `Data` 만 이 훅이 필요하다.
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
   end
 end

data/lib/keycloak_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeycloakSdk
-  VERSION = "1.0.0"
+  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.0
+  version: 1.1.0
 platform: ruby
 authors:
 - xzawed