sdk/java | XID

Java 17+ 服务端 SDK，提供 networkless JWT 验证、HTTP 请求认证和 webhook 签名校验。

状态

已在本地实现并验证。针对真实 XID 实例的 IdP 往返验证（JWKS 获取、token 签名/验证）尚未执行，生产使用前必须完成。

Registry 状态:UNPUBLISHED。此 SDK 只能从仓库源码 checkout 安装；不要使用外部 package registry。

请求认证默认仅接受 Bearer。只有配置精确名称时才读取应用自有 JWT cookie。SDK 绝不扫描或本地验证 opaque __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 并作为单例使用。

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 签发方；必须与 token iss 完全匹配
`.audience(String)`	`null`	期望的 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 读取超时

平台注意事项

使用 nimbus-jose-jwt 进行 JWT/JWKS 解析。ES256 为主要算法；支持 RS256 和 PS256。
所有公开 API 均为同步且线程安全。
通过 SLF4J facade 记录日志；请自行引入实现（Logback、Log4j2）。
异常层级：XidException -> XidTokenException、XidJwksException、XidWebhookException。