keycloak-sdk 0.1.0.rc1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4eb3a4588a71244645523375b79cbdbef40d27a027facea631d923f1f75b6fb8
-  data.tar.gz: c54cb3c59bd0c5064210a5c87feeeb6b9b56a7870c033faaf27ab767dade080f
+  metadata.gz: 8c092fe05aa83b05dbdeff11100f82093a4e757085d503c9e7f0bf2c25686823
+  data.tar.gz: ca6060f7b57451442cb91d57df7d2d711d7ce5568dd8e60dcd2a120aa9df9a64
 SHA512:
-  metadata.gz: 212c4c09ee351c966aa96ee9c6727056faab13dbc7865d969613f9ecfc7eae503071354f7da283c439cce5135428f9647a71949b06e1777765ff19fba1beb490
-  data.tar.gz: 4d7e28fa1428d4b6b3237b21a523d072f698b142a763f5160a2fa414dd030b0e2b42c37d97f653ed642282e3734d07422df3e80771aa337738b394a2148b33e9
+  metadata.gz: f0acfdff469b5e3b7962e93219394ec0cf982e0bfa9cd779f5cf57696c832bd36102904338fb8e94aa19e54e8aed5f1a5a975bfeadd8c54742c97fecbbb3756a
+  data.tar.gz: 61043f7b7e7912fb3c3fbb5d29a006483dbc16e768f0b1678e60ccfb1725901573bd4538762ea57dda26a8beca1f0a03d7ca94d996e1c656ef676692da68f09a

data/README.md

@@ -2,8 +2,6 @@
 
 Authentication (OIDC / OAuth2) and the Admin REST API for [Keycloak](https://www.keycloak.org/) behind one consistent facade, with hardened JWT validation.
 
-English · [한국어](https://github.com/xzawed/KeyCloakSDK/blob/main/ruby/README.ko.md)
-
 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).
 
 > **Pre-release** — the first release candidate (`0.1.0.rc1`) is on RubyGems; there is no stable release yet. ⚠️ **RubyGems does not install a pre-release by default**: a bare `gem install keycloak-sdk` finds nothing until a stable version exists. Ask for it explicitly — `gem install keycloak-sdk --pre`, or pin the exact version as shown below.
@@ -68,6 +66,7 @@ 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.
+- **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).
 
 Masking covers this SDK's own `#inspect`; it cannot cover what your logging framework or a backtrace does with a value you hand it. Ruby has no erasable string type, so the client secret lives in an ordinary `String` for its lifetime — masking is defence in depth, not an erasure guarantee.

data/lib/keycloak_sdk/auth_client.rb

@@ -19,23 +19,25 @@ module KeycloakSdk
       configure_rack_oauth2_timeouts(config)
     end
 
-    def create_authorization_request(redirect_uri:, scopes: nil, state: SecureRandom.urlsafe_base64(24), nonce: nil)
+    def create_authorization_request(redirect_uri:, scopes: nil, state: SecureRandom.urlsafe_base64(24),
+                                     nonce: SecureRandom.urlsafe_base64(24))
       verifier = SecureRandom.urlsafe_base64(64)
       challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
       params = {
         scope: (scopes || @config.scopes).join(" "),
         state: state,
+        nonce: nonce,
         code_challenge: challenge,
         code_challenge_method: :S256
       }
-      params[:nonce] = nonce if nonce
       url = oauth_client(redirect_uri: redirect_uri).authorization_uri(params)
-      AuthorizationRequest.new(url: url.to_s, state: state, code_verifier: verifier)
+      AuthorizationRequest.new(url: url.to_s, state: state, code_verifier: verifier, nonce: nonce)
     end
 
-    # `expected_nonce`가 주어지면(create_authorization_request가 돌려준 nonce) 응답 id_token을
+    # `expected_nonce`가 주어지면(create_authorization_request가 항상 돌려주는 nonce) 응답 id_token을
     # realm JWKS로 서명·iss·aud·exp까지 강화 검증한 뒤 nonce 클레임을 대조한다 — OIDC nonce 재생
-    # 방지. 불일치·부재·검증실패는 모두 거부(fail-closed). 생략 시 id_token 검증을 건너뛴다(무-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

data/lib/keycloak_sdk/config.rb

@@ -3,15 +3,31 @@
 module KeycloakSdk
   # 불변 설정. 생성 시 검증하고 freeze한다. client_secret은 inspect에서 마스킹.
   class Config
+    # JWKS 최소 재조회 간격 기본값의 **유일한 정의 자리**(초). DoS 증폭 상한이고 아홉 언어가
+    # 같은 값으로 정렬돼 있다 — `scripts/test/test-security-defaults.sh`가 아홉 언어 코드와
+    # 소비자 문서를 함께 대조한다.
+    #
+    # ⚠️ 이 숫자를 다른 곳에 다시 적지 말 것. 예전에는 여기 30.0, `JwksStore#initialize`에 10.0으로
+    # **두 번** 적혀 있었다. `JwksStore`는 평범한 public 클래스라 소비자가 직접 생성하면
+    # (파사드를 거치지 않으면) 문서가 말하는 30초가 아니라 10초를 받아 **IdP를 3배 자주** 때렸다.
+    # 한글 README도 그 10.0을 그대로 옮겨 적고 있었다(2026-08-12 문서 감사 → 2026-08-13 Task D1).
+    DEFAULT_JWKS_MIN_REFETCH = 30.0
+
+    # JWT `exp`/`nbf` 검증의 시계 오차 허용치 기본값(초). 이것도 아홉 언어 공동 불변식이다 —
+    # 한 언어만 커지면 **그 언어에서만 만료된 토큰이 더 오래 통과한다**.
+    # ⚠️ `JwtValidator#initialize`가 같은 값을 두 번째로 적고 있었다(둘 다 30이라 아직 갈리지는
+    # 않았으나 JWKS가 10.0/30.0으로 갈린 것과 똑같은 모양이다). 그 자리는 이제 이 상수를 참조한다.
+    DEFAULT_CLOCK_SKEW = 30
+
     attr_reader :server_url, :realm, :client_id, :client_secret,
                 :scopes, :signature_algorithms, :connect_timeout, :read_timeout, :clock_skew,
                 :jwks_min_refetch, :expected_audience
 
     def initialize(server_url:, realm:, client_id:, client_secret: nil,
                    scopes: ["openid"], signature_algorithms: ["RS256"],
-                   connect_timeout: 10, read_timeout: 10, clock_skew: 30,
-                   jwks_min_refetch: 30.0, expected_audience: nil)
-      @server_url = normalize_required("server_url", server_url).sub(%r{/+\z}, "")
+                   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))
       @realm = normalize_required("realm", realm)
       @client_id = normalize_required("client_id", client_id)
       @client_secret = client_secret
@@ -22,7 +38,7 @@ module KeycloakSdk
       @connect_timeout = positive("connect_timeout", connect_timeout)
       @read_timeout = positive("read_timeout", read_timeout)
       @clock_skew = non_negative("clock_skew", clock_skew)
-      # 미해결 kid로 인한 JWKS 재조회의 최소 간격(초, 기본 10.0) — DoS 증폭 상한.
+      # 미해결 kid로 인한 JWKS 재조회의 최소 간격(초) — DoS 증폭 상한. 기본값은 위 상수.
       @jwks_min_refetch = non_negative("jwks_min_refetch", jwks_min_refetch)
       # 토큰 aud에 들어있어야 할 값(기본 nil = client_id). 기본 realm은 client-credentials 토큰의
       # aud에 client_id를 넣지 않으므로, realm이 실제로 발급하는 리소스/오디언스를 지정한다.
@@ -39,6 +55,18 @@ module KeycloakSdk
 
     private
 
+    # 후행 슬래시 제거. 정규식(`sub(%r{/+\z}, "")`)이 아니라 선형 스캔인 이유는 **동형성**이다 —
+    # 같은 일을 하는 아홉 언어 중 go(`TrimRight`)·dotnet(`TrimEnd`)·php(`rtrim`)·rust
+    # (`trim_end_matches`)·kotlin(`trimEnd`) 다섯이 선형 문자열 트림을 쓰고, 정규식을 쓰던 것은
+    # java·node·ruby 셋뿐이었다. java/node는 SonarCloud S8786(정규식 초선형 백트래킹)으로 지적됐고
+    # ruby는 지적되지 않았지만, 셋을 함께 옮겨야 "같은 개념은 같은 모양"이라는 이 저장소의 전제가
+    # 유지된다. 동작은 정규식과 동일하다(후행 슬래시 전부 제거, 내부 슬래시 보존).
+    def strip_trailing_slashes(str)
+      i = str.length
+      i -= 1 while i.positive? && str[i - 1] == "/"
+      str[0, i]
+    end
+
     def normalize_required(name, value)
       raise ConfigError, "#{name} is required" if value.nil?
 

data/lib/keycloak_sdk/jwks_store.rb

@@ -8,7 +8,10 @@ module KeycloakSdk
   # 미해결 kid(force:true)만 재조회하며, rate-limit gate는 재조회 결정 시점에 stamp한다
   # (성공 아님 — IdP 장애창에서 위조 kid 폭주에도 재조회를 상한한다). Go/Rust/Python 동형.
   class JwksStore
-    def initialize(jwks_url:, http:, min_refetch: 10.0)
+    # ⚠️ 기본값을 여기 숫자로 적지 말 것 — `Config`가 유일한 정의 자리다. 이 클래스는 평범한
+    # public 클래스라 소비자가 파사드를 거치지 않고 직접 생성할 수 있고, 예전에는 그 경로가
+    # 문서의 30초가 아니라 10초를 받아 IdP를 3배 자주 때렸다(2026-08-13 Task D1).
+    def initialize(jwks_url:, http:, min_refetch: Config::DEFAULT_JWKS_MIN_REFETCH)
       @jwks_url = jwks_url
       @http = http
       @min_refetch = min_refetch

data/lib/keycloak_sdk/jwt_validator.rb

@@ -7,7 +7,10 @@ module KeycloakSdk
   # RS256 핀(none/confusion 구조적 거부)·iss 정확·aud 포함·exp 필수·nbf·클록스큐.
   # 키는 DoS-safe JwksStore로 조회한다(위조 서명은 재조회 미유발). 헤더 alg는 검증 알고리즘 선택에 미사용.
   class JwtValidator
-    def initialize(issuer:, audience:, jwks_store:, algorithms: ["RS256"], clock_skew: 30)
+    # ⚠️ `clock_skew` 기본값을 여기 숫자로 적지 말 것 — `Config`가 유일한 정의 자리다(Task D1과
+    # 같은 부류). 이 클래스도 public이라 소비자가 직접 생성할 수 있고, 두 자리가 갈리면 그
+    # 경로에서만 만료된 토큰이 더 오래 통과한다.
+    def initialize(issuer:, audience:, jwks_store:, algorithms: ["RS256"], clock_skew: Config::DEFAULT_CLOCK_SKEW)
       # ruby-jwt의 verify_iss/verify_aud 빌더는 값이 nil이면 조용히 no-op이 되어
       # verify_iss:true/verify_aud:true를 켜도 검사를 건너뛴다 — fail-closed로 방어.
       raise ConfigError, "issuer is required" if issuer.nil? || issuer.to_s.strip.empty?

data/lib/keycloak_sdk/tokens.rb

@@ -47,9 +47,11 @@ module KeycloakSdk
   end
 
   # authorization-code 흐름 시작 값(PKCE code_verifier 포함·inspect 마스킹).
-  AuthorizationRequest = Data.define(:url, :state, :code_verifier) do
+  # nonce는 인가 URL에 실리는 재생 방지 값이라 비밀이 아니다(state와 동급 — code_verifier만 마스킹).
+  AuthorizationRequest = Data.define(:url, :state, :code_verifier, :nonce) do
     def inspect
-      "#<KeycloakSdk::AuthorizationRequest url=#{url.inspect} state=#{state.inspect} code_verifier=\"***\">"
+      "#<KeycloakSdk::AuthorizationRequest url=#{url.inspect} state=#{state.inspect} " \
+        "nonce=#{nonce.inspect} code_verifier=\"***\">"
     end
     alias_method :to_s, :inspect
   end

data/lib/keycloak_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeycloakSdk
-  VERSION = "0.1.0.rc1"
+  VERSION = "0.1.0"
 end

metadata

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