sdk/java | XID

SDK de servidor Java 17+ para verificação JWT sem rede, autenticaçãode requisições HTTP 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

Java 17+ e Maven obrigatórios.

<!-- 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>

Início rápido

Construa um XidClient na inicialização do aplicativo e use-ocomo 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");
}

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

Verifica 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	Padrão	Descrição
`.issuer(String)`	obrigatório	Emissor OIDC; deve corresponder exatamente ao iss do token
`.audience(String)`	`null`	aud esperado; null ignora a validação
`.webhookSecret(String)`	`null`	Segredo do webhook (prefixo `whsec_` ou base64 puro)
`.jwksCacheDuration(Duration)`	1 hora	TTL do cache em memória do JWKS
`.clockSkewTolerance(Duration)`	30 segundos	Tolerância de desvio de relógio para exp/nbf
`.connectTimeout(Duration)`	5 segundos	Timeout de conexão HTTP para busca de JWKS
`.readTimeout(Duration)`	10 segundos	Timeout de leitura HTTP para busca de JWKS

Notas da plataforma

Usa nimbus-jose-jwt para parsing de JWT/JWKS. ES256 éprimário; RS256 e PS256 são suportados.
Todas as APIs públicas são síncronas e thread-safe.
Logging via fachada SLF4J; traga sua própria implementação (Logback,Log4j2).
Hierarquia de exceções: XidException ->XidTokenException, XidJwksException,XidWebhookException.