sdk/ruby | XID

네트워크 호출 없는 JWT 검증, Rack/Rails 요청 인증, webhook 서명 검증을 위한 Ruby 서버 SDK.

상태

로컬에서 구현 및 검증되었습니다. 실제 IdP 왕복 검증(JWKS 가져오기, 실제 XID 인스턴스에 대한 토큰 서명/검증)은 아직 수행되지 않았으며 프로덕션 사용 전에 완료되어야 합니다.

설치

# Gemfile
gem "xid"

bundle install

빠른 시작

require "xid"

Xid.configure do |c|
  c.issuer         = "https://xid.dev"
  c.audience       = "your_client_id"
  c.webhook_secret = "whsec_AbCdEf..."
end

# Verify a token
begin
  claims = Xid.verify_token(raw_token)
  puts claims.sub    # => "usr_abc123"
  puts claims.scope  # => "openid profile email"
rescue Xid::TokenVerificationError => e
  puts "Token invalid: #{e.message}"
end

Rack/Rails 요청 인증

# Sinatra before-filter
before do
  auth = Xid.authenticate_request(request)
  halt 401, "Unauthorized" unless auth.signed_in?
  @current_user_id = auth.claims.sub
end

# Rack middleware (env-based)
auth = Xid.authenticate_request(env)
unless auth.signed_in?
  return [401, { "Content-Type" => "application/json" },
          [JSON.generate({ error: auth.reason })]]
end

webhook 검증

# Rails controller action
def receive
  raw_body = request.raw_post
  payload = Xid.verify_webhook(request.headers.to_h, raw_body)
  handle_event(payload["type"], payload["data"])
  head :ok
rescue Xid::WebhookVerificationError
  head :bad_request
end

다중 issuer 설정

config_a = Xid::Configuration.new
config_a.issuer   = "https://tenant-a.xid.dev"
config_a.audience = "client_a"
client_a = Xid::Client.new(config_a)
claims = client_a.verify_token(token)

설정 옵션

키	기본값	설명
`issuer`	`https://xid.dev`	OIDC 발급자 URL
`audience`	`nil`	예상 aud 클레임; nil이면 검증을 건너뜁니다
`jwks_ttl`	`3600`	초 단위 JWKS 로컬 캐시 TTL
`leeway`	`60`	초 단위 JWT 클럭 편차 허용 범위
`webhook_secret`	`nil`	`whsec_` 접두사가 있는 webhook 서명 시크릿
`webhook_tolerance`	`300`	초 단위 Webhook 재사용 방지 윈도우
`cookie_name`	`__xid_token`	액세스 토큰 추출을 위한 cookie 키

플랫폼 참고 사항

jwt gem(ES256/RS256 지원)에 의존합니다. Ruby 3.1 이상이 필요합니다.
Xid.authenticate_request는 Rack env 해시와 Rack Request 객체를 모두 허용합니다.
예외 계층 구조: Xid::Error -> ConfigurationError, JwksError, TokenVerificationError, WebhookVerificationError.