sdk/java | XID

Java-17+-Server-SDK für netzwerklose JWT-Prüfung,HTTP-Anfrage-Authentifizierung und Webhook-Signaturvalidierung.

Zustand

Implementiert und lokal verifiziert. Die echteIdP-Round-Trip-Verifizierung (JWKS-Abruf, Token-Signierung/Prüfung gegeneine Live-XID-Instanz) wurde noch nicht durchgeführt und muss vor demProduktionseinsatz abgeschlossen werden.

Registry-Status: UNPUBLISHED. Installieren Sie dieses SDK nur aus einem Checkout des Repository-Quellcodes; verwenden Sie keine externe Paket-Registry.

Die Anfrageauthentifizierung akzeptiert standardmäßig nur Bearer. Ein anwendungseigenes JWT-Cookie wird nur gelesen, wenn sein exakter Name konfiguriert ist. Das opake Core-Cookie __Host-xid.rt.* wird niemals durchsucht oder lokal verifiziert; tauschen Sie es aus, indem Sie den vollständigen Cookie-Header ohne Weiterleitungen an den exakt gleichursprünglichen Endpunkt POST /v1/sessions/token weiterleiten, und akzeptieren Sie nur eine Antwort, die ausschließlich das Feld token enthält.

Installieren

Java 17+ und Maven erforderlich.

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

Schnellstart

Erstellen Sie beim Anwendungsstart einen XidClient und verwendenSie ihn als 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");
}

HTTP-Anfrage authentifizieren

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"
);

Webhook prüfen

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

Methode	Standard	Beschreibung
`.issuer(String)`	erforderlich	OIDC-Issuer; muss exakt mit dem Token-iss übereinstimmen
`.audience(String)`	`null`	Erwarteter aud; null überspringt die Validierung
`.webhookSecret(String)`	`null`	Webhook-Secret (`whsec_`-Prefix oder rohes Base64)
`.jwksCacheDuration(Duration)`	1 Stunde	JWKS-In-Memory-Cache-TTL
`.clockSkewTolerance(Duration)`	30 Sekunden	exp/nbf-Taktversatztoleranz
`.connectTimeout(Duration)`	5 Sekunden	HTTP-Verbindungs-Timeout für den JWKS-Abruf
`.readTimeout(Duration)`	10 Sekunden	HTTP-Lese-Timeout für den JWKS-Abruf

Plattformhinweise

Verwendet nimbus-jose-jwt für JWT/JWKS-Parsing. ES256 ist primär;RS256 und PS256 werden unterstützt.
Alle öffentlichen APIs sind synchron und threadsicher.
Logging über die SLF4J-Fassade; bringen Sie Ihre eigene Implementierungmit (Logback, Log4j2).
Ausnahmehierarchie: XidException -> XidTokenException,XidJwksException, XidWebhookException.