sdk/ruby | XID

SDK de servidor Ruby para verificación JWT sin llamadas de red, autenticación de solicitudes Rack/Rails y validación de firma de webhook.

Estado

Implementado y verificado localmente. La verificación de ida y vuelta contra un IdP real (obtención de JWKS, firma/verificación de tokens contra una instancia XID en producción) aún no se ha realizado y debe completarse antes del uso en producción.

Instalación

# Gemfile
gem "xid"

bundle install

Inicio 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

Autenticar una solicitud 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

Verificar 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

Configuración multi-emisor

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)

Opciones de configuración

Clave	Por defecto	Descripción
`issuer`	`https://xid.dev`	URL del emisor OIDC
`audience`	`nil`	Claim aud esperado; nil omite la validación
`jwks_ttl`	`3600`	TTL del caché local de JWKS en segundos
`leeway`	`60`	Tolerancia de desfase de reloj JWT en segundos
`webhook_secret`	`nil`	Secreto de firma del webhook con prefijo `whsec_`
`webhook_tolerance`	`300`	Ventana de repetición del webhook en segundos
`cookie_name`	`__xid_token`	Clave de cookie para extraer el access token

Notas de plataforma

Requiere la gema jwt (soporte ES256/RS256). Se necesita Ruby 3.1+.
Xid.authenticate_request acepta tanto un hash de entorno Rack como un objeto Request de Rack.
Jerarquía de excepciones: Xid::Error -> ConfigurationError, JwksError, TokenVerificationError, WebhookVerificationError.