sdk/java | XID

ネットワークレス JWT 検証、HTTP リクエスト認証、webhook 署名検証用の Java 17+ サーバー SDK。

状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 XID インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な __Host-xid.rt.* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

インストール

Java 17+ と 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>

クイックスタート

アプリケーション起動時に XidClient を 1 つ作成し、シングルトンとして使用します。

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 リクエストを認証します

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 を検証

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

方式	デフォルト	説明
`.issuer(String)`	必須	OIDC 発行者。トークンの iss と完全に一致する必要があります
`.audience(String)`	`null`	expected aud。null は検証をスキップします
`.webhookSecret(String)`	`null`	webhook シークレット（`whsec_` プレフィックスまたは生 base64）
`.jwksCacheDuration(Duration)`	1 時間	JWKS メモリ内キャッシュ TTL
`.clockSkewTolerance(Duration)`	30 秒	exp/nbf クロックスキュー許容値
`.connectTimeout(Duration)`	5 秒	JWKS 取得の HTTP 接続タイムアウト
`.readTimeout(Duration)`	10 秒	JWKS 取得の HTTP 読み取りタイムアウト

プラットフォームの注意事項

JWT/JWKS 解析に nimbus-jose-jwt を使用します。ES256 を主として、RS256 と PS256 もサポートしています。
すべての公開 API は同期的でスレッドセーフです。
SLF4J ファサード経由のログ記録。実装は自前で用意してください（Logback、Log4j2）。
例外階層：XidException -> XidTokenException、XidJwksException、XidWebhookException。