keycloak-sdk 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc6cc81e7537b1962108102b160aaeb30e45d1018ac533f834204dd58c69af3f
-  data.tar.gz: 172f64d5db58105f0402ecbe1821ed2e2c2f2910139c75144b788c38fa170c5c
+  metadata.gz: b1a2f1983231445d40411139a273115f4680aced0fe873b06a26bf0965e050cb
+  data.tar.gz: 5c5b50cdfca4f6839d2bcb94a9a107f0772bc3a4dad386a43b77ccc8b44a37b7
 SHA512:
-  metadata.gz: 19f5d3264eaec1620a68a509bcfdfe5c7180a1e7bc90867f96ffce31901ce0670e06a80d8925655e4977a13f6e1675936e59e4920cd431087372c06a0725d05c
-  data.tar.gz: 1b534ae18c8a9e1cb7bbf492ccf9713bb9fee474afd0348d05b43b6c9cfd3e22fe773654c615f6e568609c3644603822a70330184d42fc97fb2133658fcaef89
+  metadata.gz: dcde89692c25c6ab41a45363018c7b47d8d629d45ce5660f74f80f1025394438314dee56e70b4e2e91d3fa63155589867ddbded27a91d79e744115ca0880a8de
+  data.tar.gz: 4c37d217507bdee67f59b96b2e130cc057cab28a19c7ddf1686d517c0ea18c4dccd208bfb04cb2916673dff7216ffee9e029c49d309f20fe26a5575f5bef7114

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.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.
+> **`1.3.0` is on RubyGems** — a minor release on top of `1.2.0`; `1.0.0` was the first release carrying the stability guarantee. A bare `gem install keycloak-sdk` resolves it. **Security**: token, introspection and logout responses — on the grants, `introspect`, `logout` and the admin client's `ClientCredentialsTokenProvider` — are now read only up to 1,048,576 bytes; a usable token padded with 32 MiB of JSON whitespace used to be read whole, and `logout` read any body to the end. The cap is 16 times the longest bearer a default Keycloak 26.6 accepts, so no token a server accepts is refused; a larger response raises `KeycloakSdk::TransportError` (`token response exceeds 1048576 bytes` and the like) whatever its status, and the admin client sends no admin request. A response that decodes to invalid UTF-8 and an access token that a header cannot carry now raise SDK errors instead of a raw `ArgumentError` or `Encoding::CompatibilityError` — the admin client's quoted the whole bearer token. An invalid-UTF-8 input to `validate`, `introspect`, `logout` or a grant now raises an SDK error too (`TokenValidationError`, or `AuthError` without a request). ⚠️ **Token, introspection, logout and JWKS requests now send `Accept-Encoding: identity`**, so a server that answers them with gzip anyway fails. ⚠️ **The grants now go out on the SDK's own connection** rather than rack-oauth2's process-wide one: `Config` timeouts apply per client and the `User-Agent` becomes Faraday's default, while client authentication, parameters and error handling are unchanged; an empty `code` or `refresh_token` raises `AuthError` without a request. **Added**: `KeycloakSdk::Http::TOKEN_RESPONSE_MAX_BYTES` and the helpers `Http.read_capped`, `Http.decode_json` and `Http.utf8?`.
 
 ## Requirements
 
@@ -55,7 +55,7 @@ client.admin.users.delete(user_id)
 client.close
 ```
 
-> **Audience:** validation requires the token's `aud` to contain `client_id`. A stock realm does *not* put the client id in a client-credentials token's `aud`, so on a default realm either pass `expected_audience: "my-api"` (the audience your realm actually issues), or add an *Audience* protocol mapper to the client in Keycloak.
+> **Audience:** validation requires the token's `aud` to contain `client_id`. A stock realm does *not* put the client id in a client-credentials token's `aud`, so on a default realm either pass `expected_audience: "my-api"` (the audience your realm actually issues), or add an *Audience* protocol mapper to the client in Keycloak. `expected_audience` applies to access tokens (`validate`) only: the `id_token` that `exchange_code(expected_nonce:)` validates must always carry `client_id` in `aud` (OIDC Core §3.1.3.7).
 
 The five admin resources — `users` / `clients` / `roles` / `groups` / `realms` — offer symmetric CRUD, and `client.admin.raw` is the escape hatch to the underlying bearer-authenticated `Faraday::Connection`.
 

data/lib/keycloak_sdk/admin/bearer_auth.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "net/http"
 
 module KeycloakSdk
   module Admin
@@ -12,7 +13,36 @@ module KeycloakSdk
       end
 
       def on_request(env)
-        env.request_headers["Authorization"] = "Bearer #{@token_provider.access_token}"
+        token = @token_provider.access_token
+        sendable!(token) if token.is_a?(String)
+        env.request_headers["Authorization"] = "Bearer #{token}"
+      end
+
+      private
+
+      # ⚠️ **net-http 가 헤더에 실을 수 없는 Bearer 는 보내기 전에 SDK 오류로 거부한다.** net-http 는 요청 헤더를 만들
+      # 때(`initialize_http_header`) CR·LF 면 헤더 값을 **통째로 인용한** raw ArgumentError(= Bearer 누출)를,
+      # `MAX_FIELD_LENGTH`(65,536)를 넘으면 raw ArgumentError 를, 잘못된 UTF-8 이면 `strip` 의 raw
+      # Encoding::CompatibilityError 를 낸다 — 셋 다 admin 경계(`rescue Faraday::Error`)를 지나 샜다(실측).
+      # ⚠️ 고쳐 쓰지 않는다(잘라내거나 바꿔 보내면 다른 토큰이다). NUL·U+00FF 위 문자는 net-http 가 막지 않으므로
+      # 그대로 보내고 판정은 서버에 맡긴다. 메시지에는 토큰을 싣지 않는다(길이만).
+      def sendable!(token)
+        raise AuthError, "admin request not sent: the access token is not valid UTF-8" unless token.valid_encoding?
+
+        if token.match?(/[\r\n]/)
+          raise AuthError, "admin request not sent: the access token holds CR or LF, which an HTTP header cannot carry"
+        end
+
+        limit = field_limit
+        return if limit.nil? || "Bearer ".bytesize + token.bytesize <= limit
+
+        raise AuthError, "admin request not sent: the access token (#{token.bytesize} bytes) does not fit an " \
+                         "HTTP header field (#{limit} bytes with \"Bearer \")"
+      end
+
+      # 이 SDK 의 어댑터는 net-http 로 고정돼 있다(`Http.build`). 그 상한이 없는 net-http 판은 길이로 막지 않는다.
+      def field_limit
+        Net::HTTPHeader::MAX_FIELD_LENGTH if defined?(Net::HTTPHeader::MAX_FIELD_LENGTH)
       end
     end
   end

data/lib/keycloak_sdk/auth_client.rb

@@ -4,9 +4,11 @@ require "rack/oauth2"
 require "securerandom"
 require "digest"
 require "base64"
+require "uri"
 
 module KeycloakSdk
-  # 인증 파사드. rack-oauth2를 래핑(그랜트·PKCE)하고 introspection(RFC7662)·logout은 Faraday로 손수 수행한다.
+  # 인증 파사드. 인가 URL(PKCE)은 rack-oauth2 로 만들고, 세 그랜트·introspection(RFC7662)·logout 은 SDK 의 Faraday
+  # 커넥션으로 직접 보낸다 — 토큰 응답 본문을 상한까지만 읽어야 하는데 rack-oauth2 는 자기 커넥션으로 통째로 읽는다.
   # TokenProvider를 구현하지만(직접 사용용), admin은 캐싱 ClientCredentialsTokenProvider를 별도로 쓴다(§4).
   class AuthClient
     include TokenProvider
@@ -39,25 +41,23 @@ module KeycloakSdk
     end
 
     # `expected_nonce`가 주어지면(create_authorization_request가 항상 돌려주는 nonce) 응답 id_token을
-    # realm JWKS로 서명·iss·aud·exp까지 강화 검증한 뒤 nonce 클레임을 대조한다 — OIDC nonce 재생
+    # realm JWKS로 서명·iss·aud(client_id)·exp까지 강화 검증한 뒤 nonce 클레임을 대조한다 — OIDC nonce 재생
     # 방지. 불일치·부재·검증실패는 모두 거부(fail-closed). 생략 시 id_token 검증을 건너뛴다
     # (여덟 언어 공통 — exchange에서 nonce를 필수로 만들지 않는다).
     def exchange_code(code:, code_verifier:, redirect_uri:, expected_nonce: nil)
-      client = oauth_client(redirect_uri: redirect_uri)
-      client.authorization_code = code
-      token_set = token_request("authorization_code exchange") { client.access_token!(code_verifier: code_verifier) }
+      token_set = token_request("authorization_code exchange",
+                                { grant_type: "authorization_code", code: code, redirect_uri: redirect_uri,
+                                  code_verifier: code_verifier }, required: :code)
       verify_nonce!(token_set.id_token, expected_nonce) unless expected_nonce.nil?
       token_set
     end
 
     def refresh(refresh_token:)
-      client = oauth_client
-      client.refresh_token = refresh_token
-      token_request("refresh") { client.access_token! }
+      token_request("refresh", { grant_type: "refresh_token", refresh_token: refresh_token }, required: :refresh_token)
     end
 
     def client_credentials_token
-      token_request("client-credentials") { oauth_client.access_token!(scope: @config.scopes.join(" ")) }
+      token_request("client-credentials", { grant_type: "client_credentials", scope: @config.scopes.join(" ") })
     end
 
     # TokenProvider 계약(직접 사용용). admin은 캐싱 provider를 별도로 쓴다.
@@ -66,9 +66,10 @@ module KeycloakSdk
     end
 
     def introspect(token)
-      resp = @http.post(@endpoints.introspection, {
-                          token: token, client_id: @config.client_id, client_secret: @config.client_secret
-                        })
+      form = form!("introspection", token: token, client_id: @config.client_id, client_secret: @config.client_secret)
+      resp = Http.decode_json(Http.read_capped(@http, :post, @endpoints.introspection,
+                                               body: form, max_bytes: Http::TOKEN_RESPONSE_MAX_BYTES,
+                                               what: "introspection"))
       raise AuthError, "introspection failed: HTTP #{resp.status}" unless resp.success?
 
       IntrospectionResult.from_response(resp.body)
@@ -76,12 +77,16 @@ module KeycloakSdk
       raise TransportError, "introspection transport error: #{RedactedCause.describe(e)}", cause: RedactedCause.new(e)
     end
 
+    # 본문은 쓰지 않지만 읽는다 — `TOKEN_RESPONSE_MAX_BYTES` 까지만(넘으면 상태와 무관하게 TransportError).
+    # 해석은 커넥션의 json 미들웨어가 하던 그대로 남긴다: JSON 이라면서 JSON 이 아닌 본문은 지금처럼 TransportError 다.
+    # UTF-8 검사는 걸지 않는다(`check_utf8: false`) — 값을 쓰지 않아 지킬 것이 없고, 걸면 400 이 오류 본문의 바이트에
+    # 따라 AuthError 에서 TransportError 로 바뀐다(hostile_token_response_spec 의 u2). 해석은 상태 검사보다 먼저다.
     def logout(refresh_token:)
-      resp = @http.post(@endpoints.end_session, {
-                          client_id: @config.client_id, client_secret: @config.client_secret,
-                          refresh_token: refresh_token
-                        })
-      raise AuthError, "logout failed: HTTP #{resp.status}" unless resp.success?
+      form = form!("logout", client_id: @config.client_id, client_secret: @config.client_secret,
+                             refresh_token: refresh_token)
+      resp = Http.read_capped(@http, :post, @endpoints.end_session,
+                              body: form, max_bytes: Http::TOKEN_RESPONSE_MAX_BYTES, what: "logout")
+      raise AuthError, "logout failed: HTTP #{resp.status}" unless Http.decode_json(resp, check_utf8: false).success?
 
       nil
     rescue Faraday::Error => e
@@ -97,6 +102,8 @@ module KeycloakSdk
     # rack-oauth2의 프로세스 전역 HTTP 타임아웃을 Config로 설정한다(require 시점 하드코딩 대신).
     # 타임아웃은 Faraday::Connection이 아니라 그 #options(Faraday::RequestOptions)에 있다
     # (Connection에 open_timeout=/timeout= 세터가 없어 NoMethodError — 게차 참조).
+    # ⚠️ SDK 의 토큰 요청은 이제 rack-oauth2 의 연결을 타지 않는다(그랜트는 `token_request` 가 직접 보낸다) — 이 등록이
+    # 닿는 것은 같은 프로세스의 다른 rack-oauth2 사용자뿐이다. 등록은 first-wins(`@@http_config ||= block`)다.
     def configure_rack_oauth2_timeouts(config)
       Rack::OAuth2.http_config do |conn|
         conn.options.open_timeout = config.connect_timeout
@@ -104,14 +111,13 @@ module KeycloakSdk
       end
     end
 
-    # id_token의 nonce 클레임을 대조하기 전에 강화 JwtValidator로 서명·iss·aud·exp까지 검증한다
-    # (액세스 토큰과 id_token 모두 aud=client_id이므로 검증기를 공유해도 안전 — Kotlin/.NET 동형).
-    # ⚠️ `config.expected_audience`를 설정하면 이 공유 검증기가 id_token에도 그 값을 요구한다 —
-    # 이 흐름을 쓴다면 해당 오디언스를 id_token에도 매핑해야 한다(audience 매퍼의 "Add to ID token").
+    # id_token의 nonce 클레임을 대조하기 전에 강화 JwtValidator로 서명·iss·aud·exp까지 검증한다.
+    # aud 는 `expected_audience` 재정의가 아니라 **client_id** 다(OIDC Core §2·§3.1.3.7) — 재정의는 액세스 토큰의 것.
+    # 검증기(=키 저장소)는 `validate` 와 같은 하나를 쓴다.
     def verify_nonce!(id_token, expected_nonce)
       raise AuthError, "authorization_code exchange failed: missing id_token for nonce validation" if id_token.nil?
 
-      validated = @jwt_validator.validate(id_token)
+      validated = @jwt_validator.validate(id_token, audience: @config.client_id)
       return if validated.claims["nonce"] == expected_nonce
 
       raise AuthError, "authorization_code exchange failed: unexpected nonce"
@@ -119,14 +125,18 @@ module KeycloakSdk
       raise AuthError, "authorization_code exchange failed: invalid id_token: #{e.message}"
     end
 
-    # rack-oauth2 토큰 호출의 오류 경계(§4). 하위 예외는 SDK 타입이 되고 `cause` 에는 원본 대신 `RedactedCause` 가 달린다.
+    # 토큰 그랜트 하나와 그 오류 경계(§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)
+    # ⚠️ 마지막 `StandardError` 는 형식이 틀린 200 을 읽다 나는 것(NoMethodError·AttrMissing·'Unknown Token Type')과
+    # `to_token_set` 의 형 변환 실패다 — 원본이 새면 Ruby 3.2 의 NoMethodError 가 본문을 인용한다.
+    # ⚠️ 필수 값(`code`·`refresh_token`)이 비면 보내지 않는다 — rack-oauth2 의 그랜트가 하던 검사이고, 그때는 이 경계
+    # 밖에서 raw `AttrRequired::AttrMissing` 으로 샜다.
+    def token_request(operation, params, required: nil)
+      raise AuthError, "#{operation} failed: #{required} is required" if required && missing?(params[required])
+
+      to_token_set(oauth_token(post_grant(operation, params)))
     rescue Error
       raise
     rescue Rack::OAuth2::Client::Error => e
@@ -140,6 +150,50 @@ module KeycloakSdk
       raise AuthError, "#{operation} failed: unusable token response (#{e.class})", cause: RedactedCause.new(e)
     end
 
+    # 그랜트를 SDK 커넥션으로 보낸다 — 클라이언트 인증은 rack-oauth2 의 기본(`:basic`)과 같은 모양(id·secret 을
+    # 각각 form-url-encode 한 뒤 base64)이고, 빈 값은 rack-oauth2 의 `Util.compact_hash` 처럼 보내지 않는다.
+    # 본문은 `TOKEN_RESPONSE_MAX_BYTES` 까지만 읽는다.
+    def post_grant(operation, params)
+      form = form!(operation, **params).reject { |_, v| v.nil? || v.to_s.match?(/\A[[:space:]]*\z/) }
+      pair = [@config.client_id, @config.client_secret].map { |v| URI.encode_www_form_component(v) }.join(":")
+      basic = { "Authorization" => "Basic #{Base64.strict_encode64(pair)}" }
+      Http.decode_json(Http.read_capped(@http, :post, @endpoints.token,
+                                        body: form, headers: basic,
+                                        max_bytes: Http::TOKEN_RESPONSE_MAX_BYTES, what: "token"))
+    end
+
+    # rack-oauth2 의 응답 규칙(`Client#handle_response` — 2.3.0 client.rb:205-240)을 SDK 가 읽은 본문에 그대로 건다:
+    # 200·201 은 token_type 이 bearer 인 `AccessToken::Bearer`, 그 밖은 `Client::Error`(본문이 객체가 아니면 'Unknown').
+    # 그 메서드는 private 이라 규칙만 옮겼다 — 결과·오류는 rack-oauth2 의 공개 타입이라 위 오류 대응이 그대로다.
+    # 객체가 아닌 200 본문은 rack-oauth2 처럼 NoMethodError 로 떨어져 `token_request` 가 AuthError 로 바꾼다.
+    def oauth_token(resp)
+      body = resp.body
+      unless (200..201).cover?(resp.status)
+        error = body.is_a?(Hash) ? body.transform_keys(&:to_sym) : { error: "Unknown", error_description: body }
+        raise Rack::OAuth2::Client::Error.new(resp.status, error)
+      end
+
+      token_hash = body.transform_keys(&:to_sym)
+      raise "Unknown Token Type" unless token_hash[:token_type]&.downcase == "bearer"
+
+      Rack::OAuth2::AccessToken::Bearer.new(token_hash)
+    end
+
+    # rack-oauth2 의 `attr_required` 와 같은 「비었다」 — nil 이거나 빈 값(공백뿐인 문자열은 비지 않았다).
+    def missing?(value)
+      value.respond_to?(:empty?) ? value.empty? : value.nil?
+    end
+
+    # 폼 값이 잘못된 UTF-8 이면 요청 없이 거부하고(어느 자리인지만 말한다) 아니면 폼을 돌려준다. Faraday 의 폼
+    # 인코더(`Faraday::Utils.escape` 의 `gsub`)가 그것에서 raw ArgumentError 를 냈다(실측: logout·introspect 는 요청 0 건에
+    # raw, 그랜트는 「unusable token response (ArgumentError)」라는 틀린 말). 고쳐 쓰지 않는다.
+    def form!(operation, **form)
+      bad = form.find { |_, v| v.is_a?(String) && !v.valid_encoding? }
+      raise AuthError, "#{operation} failed: #{bad.first} is not valid UTF-8" if bad
+
+      form
+    end
+
     def oauth_client(redirect_uri: nil)
       Rack::OAuth2::Client.new(
         identifier: @config.client_id,

data/lib/keycloak_sdk/http.rb

@@ -1,11 +1,33 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "json"
 
 module KeycloakSdk
   # 공유 Faraday 커넥션 팩토리. 타임아웃을 config에서 주입하고,
   # follow_redirects 미들웨어를 절대 장착하지 않는다(SSRF 하드닝 — Faraday는 기본 미추종).
+  # 상한을 건 본문 읽기(`read_capped`)도 여기 있다 — 토큰·introspection·logout·JWKS 레인이 같은 기제를 쓴다.
   module Http
+    # 토큰 엔드포인트(세 그랜트 · admin 레인의 자기 토큰)·introspection·logout 응답 본문의 상한(바이트).
+    # 1 MiB 는 Keycloak 26.6 이 기본 설정으로 받는 가장 긴 Bearer(65,459 바이트 — 하나 더 길면 HTTP 431)의
+    # 16 배라 서버가 받는 토큰은 거부하지 않고, 끝없는 본문은 여기서 멈춘다.
+    # ⚠️ JWKS 의 51,200 을 빌려 쓰지 말 것 — 서비스 계정 토큰은 관리하는 realm 수만큼 자란다.
+    # ⚠️ 맨 십진 리터럴이어야 한다 — 아홉 SDK 가 같은 값을 쓰고 교차언어 가드가 이 줄을 읽는다.
+    TOKEN_RESPONSE_MAX_BYTES = 1_048_576
+
+    # ⚠️ **SDK 가 직접 읽는 요청은 인코딩 없는 본문을 청한다.** Accept-Encoding 이 없으면 net-http 가 gzip 을 청하고
+    # 스스로 푸는데, 그 inflater 는 상한에서 읽기를 끊어도 ensure 에서 `Inflater#finish` 로 **지금 읽은 압축 조각을
+    # 끝까지** 푼다 — 16 KiB 조각 하나가 공백이면 ~16 MiB 다(실측: JWKS 상한이 지켜진 채 피크 +24 MB).
+    # 요청에 이 헤더가 있으면 net-http 는 자기 것을 붙이지 않고 풀지도 않는다. 그래도 gzip 을 보내는 서버는
+    # 압축된 바이트가 그대로 와 JSON 으로 읽히지 않으므로 SDK 오류로 닫힌다.
+    IDENTITY = { "Accept-Encoding" => "identity" }.freeze
+
+    # Faraday 의 JSON 응답 규칙 그대로(JSON 콘텐츠 타입만 · 빈 본문은 nil · 해석 실패는 Faraday::ParsingError).
+    # 스트리밍으로 읽은 본문은 커넥션의 json 미들웨어가 보지 못하므로(그때 본문은 비어 있다) 여기서 같은 규칙을 건다.
+    JSON_RESPONSE = Faraday::Response::Json.new(nil, content_type: /\bjson$/)
+    UNDECODABLE = "JSON text decodes to invalid UTF-8"
+    private_constant :IDENTITY, :JSON_RESPONSE, :UNDECODABLE
+
     module_function
 
     def build(config, base_url: nil)
@@ -17,5 +39,55 @@ module KeycloakSdk
         f.adapter :net_http
       end
     end
+
+    # 요청 하나를 보내고 본문을 `max_bytes` 까지만 읽는다 — **상태와 무관하게**(오류 응답의 거대 본문도 같다).
+    # 돌려주는 응답의 `body` 는 읽은 바이트(BINARY 문자열)다. 넘으면 그 즉시 `TransportError` 이고 연결은 닫힌다.
+    #
+    # ⚠️ 판정은 청크를 **붙이기 전에** 한다 — 버퍼는 상한을 넘지 않고, 넘는 청크는 복사하지 않는다. 읽는 크기는
+    # SDK 가 정하지 못한다: net-http 가 소켓에서 16 KiB(`Net::BufferedIO::BUFSIZE`)씩 읽어 넘기므로 판정 순간
+    # 손에 든 것은 많아야 상한 + 청크 하나(16,384 바이트)다. 버퍼는 읽은 만큼만 자란다(미리 상한만큼 잡지 않는다).
+    # ⚠️ `Content-Length` 만 보면 그 헤더가 없거나 거짓인 응답을 놓친다 — 누적치로 판정한다.
+    def read_capped(conn, method, url, max_bytes:, what:, body: nil, headers: {})
+      buf = String.new(encoding: Encoding::BINARY)
+      resp = conn.run_request(method, url, body, IDENTITY.merge(headers)) do |req|
+        req.options.on_data = proc do |chunk, _received|
+          over = buf.bytesize + chunk.bytesize > max_bytes
+          raise TransportError, "#{what} response exceeds #{max_bytes} bytes" if over
+
+          buf << chunk
+        end
+      end
+      resp.env.body = buf
+      resp
+    end
+
+    # `read_capped` 의 본문을 커넥션의 json 미들웨어가 하던 그대로 해석한다(응답을 돌려준다).
+    # ⚠️ 해석한 값의 문자열이 잘못된 UTF-8 이면 해석 실패다(Faraday::ParsingError ← JSON::ParserError — 짝 없는
+    # 서로게이트 이스케이프에서 json 3 이 내는 것과 같은 모양). 고쳐 쓰지 않는다 — 그 값은 SDK 를 지나며 raw 예외가 된다.
+    # `check_utf8: false` 는 해석한 값을 하나도 쓰지 않는 호출(logout)의 것이다 — 미들웨어의 판정만 남는다.
+    def decode_json(resp, check_utf8: true)
+      JSON_RESPONSE.on_complete(resp.env)
+      return resp if !check_utf8 || utf8?(resp.body)
+
+      begin
+        raise JSON::ParserError, UNDECODABLE
+      rescue JSON::ParserError => e
+        raise Faraday::ParsingError.new(e, resp) # 원인 사슬도 json 3 의 실패와 같다(ParsingError <- ParserError)
+      end
+    end
+
+    # 해석한 JSON 값(키 포함)의 문자열이 전부 올바른 인코딩인가. 해석하지 않은 본문(BINARY)은 언제나 참이다.
+    # ⚠️ **json 버전으로 막을 수 없다** — 잠긴 json 3.0.2 도 날 잘못된 UTF-8 바이트(0xFF)는 그대로 받아 잘못된
+    # 문자열을 내고, json 2.9–2.21 은 짝 없는 **낮은** 서로게이트 이스케이프(\udc00)까지 그렇게 푼다(둘 다 실측).
+    # 그 문자열이 지나는 자리마다 raw 예외다 — OAuth 코드 대조(`match?`)의 ArgumentError, admin 헤더의
+    # Encoding::CompatibilityError(net-http `strip`), ruby-jwt base64 의 ArgumentError.
+    def utf8?(value)
+      case value
+      when String then value.valid_encoding?
+      when Hash then value.all? { |k, v| utf8?(k) && utf8?(v) }
+      when Array then value.all? { |v| utf8?(v) }
+      else true
+      end
+    end
   end
 end

data/lib/keycloak_sdk/jwks_store.rb

@@ -107,20 +107,19 @@ module KeycloakSdk
 
     def fetch
       # ⚠️ 상한은 **상태와 무관하게** 건다. 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
+      # 들어온다 — php 가 정확히 그 순서였다(상태 검사 전에 `json_decode`). 기제는 토큰 레인과 같은 `Http.read_capped`.
+      resp = Http.read_capped(@http, :get, @jwks_url, max_bytes: JWKS_MAX_BYTES, what: "JWKS")
       raise TransportError, "JWKS fetch failed: HTTP #{resp.status}" unless resp.success?
 
       # ⚠️ `on_data` 를 쓰면 Faraday 는 본문을 누적하지 않으므로 json 미들웨어가 돌지 않는다 —
       # 파싱은 여기서 한다. 파싱 실패도 경계에서 SDK 타입이 되어야 한다(§4).
+      # ⚠️ 잘못된 UTF-8 로 풀리는 본문도 해석 실패다(`Http.utf8?`) — n·e 가 그러면 ruby-jwt 의 base64 가 검증 중에
+      # raw ArgumentError 를 냈다(실측, 잠긴 json 3.0.2 에서도).
       body = begin
-        JSON.parse(buf)
+        parsed = JSON.parse(resp.body)
+        raise JSON::ParserError, "JSON text decodes to invalid UTF-8" unless Http.utf8?(parsed)
+
+        parsed
       rescue JSON::ParserError => e
         raise TransportError, "JWKS response unparsable (JSON::ParserError)", cause: RedactedCause.new(e)
       end

data/lib/keycloak_sdk/jwt_validator.rb

@@ -30,8 +30,17 @@ module KeycloakSdk
           algorithms: config.signature_algorithms, clock_skew: config.clock_skew)
     end
 
-    def validate(token)
-      payload, = JWT.decode(token, nil, true, decode_options)
+    # `audience:` 는 이 호출만의 기대 aud 다(기본 = 생성 시 값). 코드 교환이 id_token 을 client_id 로 검사할 때
+    # 쓴다 — 키 저장소(캐시 · 재조회 제한 · 백오프)는 그대로 이 인스턴스의 것 하나다.
+    # ⚠️ nil·공백은 생성자와 같이 ConfigError — ruby-jwt 는 `aud: nil` 이면 aud 검사를 건너뛴다.
+    def validate(token, audience: @audience)
+      raise ConfigError, "audience is required" if audience.nil? || audience.to_s.strip.empty?
+      # ⚠️ ruby-jwt 는 맨 먼저 토큰을 `split` 하고, 잘못된 UTF-8 이면 그것이 raw ArgumentError 다(실측).
+      if token.is_a?(String) && !token.valid_encoding?
+        raise TokenValidationError, "JWT validation failed: token is not valid UTF-8"
+      end
+
+      payload, = JWT.decode(token, nil, true, decode_options(audience))
       to_validated(payload)
     rescue JWT::DecodeError => e
       # ruby-jwt 메시지는 입력을 인용하지 않는다. 그 **원인**은 인용한다 — 조각이 JSON 이 아니면 JSON::ParserError 가
@@ -41,12 +50,12 @@ module KeycloakSdk
 
     private
 
-    def decode_options
+    def decode_options(audience)
       {
         algorithms: @algorithms,
         jwks: jwks_loader,
         verify_iss: true, iss: @issuer,
-        verify_aud: true, aud: @audience,
+        verify_aud: true, aud: audience,
         verify_expiration: true,
         verify_not_before: true,
         required_claims: %w[exp iss aud],

data/lib/keycloak_sdk/token_provider.rb

@@ -45,13 +45,14 @@ module KeycloakSdk
 
     private
 
+    # 본문은 `Http::TOKEN_RESPONSE_MAX_BYTES` 까지만 읽는다 — 넘으면 `TransportError` 이고 admin 요청은 나가지 않는다.
     def request_token
-      resp = @http.post(@token_url, {
-                          grant_type: "client_credentials",
-                          client_id: @config.client_id,
-                          client_secret: @config.client_secret,
-                          scope: @config.scopes.join(" ")
-                        })
+      resp = Http.decode_json(Http.read_capped(@http, :post, @token_url,
+                                               body: { grant_type: "client_credentials",
+                                                       client_id: @config.client_id,
+                                                       client_secret: @config.client_secret,
+                                                       scope: @config.scopes.join(" ") },
+                                               max_bytes: Http::TOKEN_RESPONSE_MAX_BYTES, what: "token"))
       unless resp.success?
         oauth = resp.body.is_a?(Hash) ? resp.body["error"] : nil
         raise AuthError.new("client-credentials token request failed: HTTP #{resp.status}", oauth_error: oauth)

data/lib/keycloak_sdk/version.rb

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

data/lib/keycloak_sdk.rb

@@ -30,4 +30,6 @@ end
 # (b) Config 타임아웃을 무시했다. 이제는 AuthClient#initialize에서 Config의 connect/read 타임아웃으로
 # 설정한다(auth_client.rb) — require 부작용 제거 + config 반영. 전역이라는 근본 한계는 남지만
 # "SDK auth를 실제로 쓸 때"로 스코프가 좁혀진다(require 시점 아님).
+# ⚠️ SDK 자신의 토큰 요청은 이 전역 연결을 타지 않는다 — 그랜트는 SDK 커넥션(`Http.build`, 클라이언트마다 Config
+# 타임아웃)으로 직접 보낸다(응답 상한 때문). rack-oauth2 의 HTTP 연결을 쓰는 SDK 경로는 이제 없다(인가 URL 조립은 네트워크가 없다).
 require "rack/oauth2"

metadata

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