---
title: "sdk/ruby"
description: "Ruby 服务端 SDK，提供 networkless JWT 验证、Rack/Rails 请求认证和 webhook 签名校验。"
locale: "zh-Hans"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/zh-hans/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/ruby

## 状态

已在本地实现并验证。针对真实 Vonvon 实例的 IdP 往返验证（JWKS 获取、token 签名/验证）尚未执行，生产使用前必须完成。

Registry 状态:UNPUBLISHED。此 SDK 只能从仓库源码 checkout 安装；不要使用外部 package registry。

请求认证默认仅接受 Bearer。只有配置精确名称时才读取应用自有 JWT cookie。SDK 绝不扫描或本地验证 opaque \_\_Host-vonvon.rt.\* Core cookie；应将完整 Cookie header 转发到 exact same-origin POST /v1/sessions/token，并禁用 redirect，且只接受仅包含 token 字段的响应。

## 安装

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

bundle install
```

## 快速开始

```ruby
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 请求

```ruby
# 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

```ruby
# 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
```

## 多签发方配置

```ruby
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` | 期望的 aud claim；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`。

Source: https://vonvon.id/zh-hans/sdks/ruby/index.mdx