keycloak-sdk 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39cf848bf3f01443707855e1a981e8bcaf4fdbb3a5ac9fbf17a7b6ac010e33f4
-  data.tar.gz: 489cfcf03654e7da757bfcd6020cf148d3fb9550c89ea9f14c09569977aa47b8
+  metadata.gz: ced74e5c197f31bcea44f678715d2c2b30d8cfe6b597393a200bda451057f582
+  data.tar.gz: ff1f1781cfc00acfcca781217eedb6be8f76c7efc72f93b49940f9a85882f1b2
 SHA512:
-  metadata.gz: a2c51c7d06751f6ae0c6ed76d83083400f679354a011d1dbc720c93fd374cf1047092c4dc8214931ea8f25fd2a6099e5103577c35aee998194e0c56b7645c9fb
-  data.tar.gz: 3d112a01d129df0a1bbebb7ef3b0ba75b4947fd5bb1014a7471beef728f2d22be9020d264f98660d887f1820e58e6014caa4bf12cd0dc8787571568b4c320a56
+  metadata.gz: 2e4564e3f092dc1161a80e4bd0bb854dd1c05b4c57dd9552db23c8607f5aace485dc5fd160dddcae0e7c27989ddf4b0f4a889e6f365345dc847504afd61c4dea
+  data.tar.gz: 2b4df9762901e5b1c7f43372952a298ee82392a6ab95cabbfd974c737213813266d7c206dcea5ee5f3509330f71a6674edc8ae5017c77a6769783cedb5356e16

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.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.
 
 ## 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,11 +1,31 @@
 # 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?

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/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/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: #{e.message}"
+      end
+      validate_key_set!(body)
+    rescue Faraday::Error => e
+      raise TransportError, "JWKS transport error: #{e.message}"
+    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/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

data/lib/keycloak_sdk/tokens.rb

@@ -4,10 +4,30 @@ 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)
+      # ⚠️ **존재 검사는 타입 검사가 아니다.** 예전에는 값을 그대로 담아 숫자·해시·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 = body["expires_in"] && Integer(body["expires_in"])
       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 +37,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 +53,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의 관심 클레임.
@@ -54,5 +85,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.0.1"
 end

metadata

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