sdk/ruby | Vonvon

ネットワークレス JWT 検証、Rack/Rails リクエスト認証、webhook 署名検証用の Ruby サーバー SDK。

状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 Vonvon インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な __Host-vonvon.rt.* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

インストール

# Gemfile
gem "vonvon", path: "../vonvon/sdk/ruby"

bundle install

クイックスタート

require "vonvon"

Vonvon.configure do |c|
  c.issuer         = "https://vonvon.id"
  c.audience       = "your_client_id"
  c.webhook_secret = "whsec_AbCdEf..."
end

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

Rack/Rails リクエストを認証します

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

# Explicit same-origin Core session -> JWT exchange
token = Vonvon.exchange_session_token(
  incoming_request_url: request.url,
  cookie_header: request.get_header("HTTP_COOKIE")
)

webhook を検証

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

マルチ発行者セットアップ

config_a = Vonvon::Configuration.new
config_a.issuer   = "https://tenant-a.vonvon.id"
config_a.audience = "client_a"
client_a = Vonvon::Client.new(config_a)
claims = client_a.verify_token(token)

設定オプション

キー	デフォルト	説明
`issuer`	`https://vonvon.id`	OIDC 発行者 URL
`audience`	`nil`	expected aud クレーム。nil は検証をスキップします
`jwks_ttl`	`3600`	JWKS ローカルキャッシュ TTL（秒）
`leeway`	`60`	JWT クロックスキュー許容値（秒）
`webhook_secret`	`nil`	`whsec_` プレフィックス付きの webhook 署名シークレット
`webhook_tolerance`	`300`	webhook リプレイウィンドウ（秒）
`cookie_name`	`disabled`	アプリケーション所有の JWT cookie 名。明示的に設定した場合のみ有効

プラットフォームの注意事項

jwt gem（ES256/RS256 サポート）が必要です。Ruby 3.1+ が必要です。
Vonvon.authenticate_request は Rack env ハッシュと Rack Request オブジェクトの両方を受け入れます。
例外階層：Vonvon::Error -> ConfigurationError、JwksError、TokenVerificationError、WebhookVerificationError。