sdk/ruby | XID

SDK de servidor Ruby para verificação JWT sem rede, autenticação derequisições Rack/Rails e validação de assinatura de webhook.

Estado

Implementado e verificado localmente. A verificação de ida e voltacom um IdP real (busca de JWKS, assinatura/verificação de tokencontra uma instância XID ativa) ainda não foi realizada e deve serconcluída antes do uso em produção.

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

A autenticação de requisições aceita somente Bearer por padrão. Um cookie JWT pertencente ao aplicativo só é lido quando seu nome exato é configurado. O cookie opaco do Core __Host-xid.rt.* nunca é pesquisado nem verificado localmente; troque-o encaminhando o header Cookie completo para o POST /v1/sessions/token da mesma origem exata, com redirects desativados, e aceite somente uma resposta que contenha apenas o campo token.

Instalar

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

bundle install

Início rápido

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

Autentica uma requisição 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

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

Verifica 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

Configuração multi-emissor

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)

Opções de configuração

Chave	Padrão	Descrição
`issuer`	`https://xid.dev`	URL do emissor OIDC
`audience`	`nil`	Claim aud esperado; nil ignora a validação
`jwks_ttl`	`3600`	TTL do cache local do JWKS em segundos
`leeway`	`60`	Tolerância de desvio de relógio JWT em segundos
`webhook_secret`	`nil`	Segredo de assinatura do webhook com prefixo `whsec_`
`webhook_tolerance`	`300`	Janela de replay de webhook em segundos
`cookie_name`	`disabled`	Nome do cookie JWT pertencente ao aplicativo; desativado salvo configuração explícita

Notas da plataforma

Depende da gem jwt (suporte ES256/RS256). Ruby 3.1+obrigatório.
Xid.authenticate_request aceita tanto um hash de env do Rackquanto um objeto Request do Rack.
Hierarquia de exceções: Xid::Error ->ConfigurationError, JwksError,TokenVerificationError, WebhookVerificationError.