sdk/java | XID

SDK serveur Java 17+ pour la vérification JWT sans réseau,l'authentification des requêtes HTTP et la validation des signatureswebhook.

Statut

Implémenté et vérifié localement. La vérification aller-retour avec unvrai IdP (récupération JWKS, signature/vérification de jeton contre uneinstance XID active) n’a pas encore été effectuée et doit être complétéeavant toute utilisation en production.

Statut du registre : UNPUBLISHED. Installez ce SDK uniquement depuis un checkout du code source du dépôt ; n’utilisez pas de registre de paquets externe.

L’authentification des requêtes accepte uniquement Bearer par défaut. Un cookie JWT détenu par l’application n’est lu que lorsque son nom exact est configuré. Le cookie Core opaque __Host-xid.rt.* n’est jamais recherché ni vérifié localement ; échangez-le en transférant le header Cookie complet vers le POST /v1/sessions/token de même origine exacte, avec les redirections désactivées, et n’acceptez qu’une réponse contenant uniquement le champ token.

Installer

Java 17+ et Maven requis.

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

Démarrage rapide

Construisez un seul XidClient au démarrage de l’application etutilisez-le comme 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");
}

Authentifier une requête 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"
);

Vérifier le 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éthode	Défaut	Description
`.issuer(String)`	requis	Émetteur OIDC ; doit correspondre exactement au iss du jeton
`.audience(String)`	`null`	Aud attendue ; null ignore la validation
`.webhookSecret(String)`	`null`	Secret webhook (préfixe `whsec_` ou base64 brut)
`.jwksCacheDuration(Duration)`	1 heure	TTL du cache JWKS en mémoire
`.clockSkewTolerance(Duration)`	30 secondes	Tolérance au décalage d’horloge pour exp/nbf
`.connectTimeout(Duration)`	5 secondes	Délai de connexion HTTP pour la récupération JWKS
`.readTimeout(Duration)`	10 secondes	Délai de lecture HTTP pour la récupération JWKS

Notes de plateforme

Utilise nimbus-jose-jwt pour l’analyse JWT/JWKS. ES256 estprincipal ; RS256 et PS256 sont pris en charge.
Toutes les API publiques sont synchrones et thread-safe.
Journalisation via la façade SLF4J ; apportez votre propre implémentation(Logback, Log4j2).
Hiérarchie d’exceptions : XidException -> XidTokenException,XidJwksException, XidWebhookException.