sdk/java | XID

SDK de servidor Java 17+ para verificación JWT sin llamadas de red, autenticación de solicitudes HTTP 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.

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

La autenticación de solicitudes acepta solo Bearer de forma predeterminada. Una cookie JWT propiedad de la aplicación solo se lee cuando se configura su nombre exacto. La cookie opaca de Core __Host-xid.rt.* nunca se busca ni se verifica localmente; intercámbiala reenviando el header Cookie completo al POST /v1/sessions/token del mismo origen exacto, con las redirecciones desactivadas, y acepta solo una respuesta que contenga únicamente el campo token.

Instalación

Se requieren Java 17+ y Maven.

<!-- First install the source checkout: cd sdk/java && mvn install -->
<dependency>
  <groupId>dev.xid</groupId>
  <artifactId>xid-sdk-java</artifactId>
  <version>0.1.0-alpha.0</version>
</dependency>

Inicio rápido

Construye un único XidClient al arrancar la aplicación y úsalo como singleton.

import dev.xid.sdk.XidClient;
import dev.xid.sdk.XidClientOptions;
import dev.xid.sdk.XidClaims;
import dev.xid.sdk.XidTokenException;
import dev.xid.sdk.XidJwksException;

XidClient xid = XidClient.create(
    XidClientOptions.builder()
        .issuer("https://xid.dev")
        .audience("your-client-id")
        .webhookSecret("whsec_xxx")
        .build()
);

try {
    XidClaims claims = xid.verifyToken(accessToken);
    String userId = claims.getSub();
    String scope  = claims.getScope();
} catch (XidTokenException e) {
    response.sendError(401, "Unauthorized: " + e.getReason());
} catch (XidJwksException e) {
    response.sendError(503, "Service unavailable");
}

Autenticar una solicitud HTTP

import dev.xid.sdk.AuthResult;

// Bearer-only by default
AuthResult result = xid.authenticateRequest(request.getHeader("Authorization"), null);

if (result.isAuthenticated()) {
    String userId = result.getClaims().get().getSub();
} else {
    response.sendError(401);
}

String token = xid.exchangeSessionToken(
    request.getRequestURL().toString(),
    request.getHeader("Cookie"),
    "/v1/sessions/token"
);

Verificar webhook

import dev.xid.sdk.XidWebhookException;

byte[] rawBody = request.getInputStream().readAllBytes();
Map<String, String> headers = Map.of(
    "svix-id",        request.getHeader("svix-id"),
    "svix-timestamp", request.getHeader("svix-timestamp"),
    "svix-signature", request.getHeader("svix-signature")
);

try {
    xid.verifyWebhook(headers, rawBody);
} catch (XidWebhookException e) {
    response.sendError(400, "Invalid webhook: " + e.getReason());
}

XidClientOptions

Método	Por defecto	Descripción
`.issuer(String)`	obligatorio	Emisor OIDC; debe coincidir exactamente con el iss del token
`.audience(String)`	`null`	aud esperado; null omite la validación
`.webhookSecret(String)`	`null`	Secreto del webhook (prefijo `whsec_` o base64 sin prefijo)
`.jwksCacheDuration(Duration)`	1 hora	TTL del caché en memoria de JWKS
`.clockSkewTolerance(Duration)`	30 segundos	tolerancia de desfase de reloj para exp/nbf
`.connectTimeout(Duration)`	5 segundos	Tiempo de espera de conexión HTTP para obtener el JWKS
`.readTimeout(Duration)`	10 segundos	Tiempo de espera de lectura HTTP para obtener el JWKS

Notas de plataforma

Usa nimbus-jose-jwt para el análisis de JWT/JWKS. ES256 es el principal; RS256 y PS256 están soportados.
Todas las APIs públicas son sincrónicas y thread-safe.
Registro mediante la fachada SLF4J; trae tu propia implementación (Logback, Log4j2).
Jerarquía de excepciones: XidException -> XidTokenException, XidJwksException, XidWebhookException.