sdk/php | XID

ネットワークレス JWT 検証、PSR-7 リクエスト認証、webhook 署名検証用の PHP 8.1+ サーバー SDK。

状態

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

インストール

PHP 8.1+ が必要です。コア依存関係は Composer が自動的に取得します。

composer require xid/xid

クイックスタート

use Xid\XidClient;
use Xid\Exception\TokenException;
use Xid\Exception\JwksException;

$xid = new XidClient([
    'issuer'   => 'https://xid.dev',
    'audience' => 'your-client-id',
    'cache'    => $psrSimpleCacheImpl, // PSR-16; null disables JWKS cache
]);

try {
    $claims = $xid->verifyToken($jwtString);
    echo $claims->sub();    // user ID
    echo $claims->scope();  // "openid profile email"
    echo implode(',', $claims->amr()); // "phr" / "otp"
} catch (TokenException $e) {
    http_response_code(401);
} catch (JwksException $e) {
    http_response_code(503);
}

PSR-7 リクエストを認証します

$result = $xid->authenticateRequest($psrRequest);

if ($result->isAuthenticated()) {
    $userId = $result->claims()->sub();
} else {
    // $result->reason() for server-side logs only
    http_response_code(401);
}

webhook を検証

use Xid\Exception\WebhookException;

try {
    $payload = $xid->verifyWebhook($psrRequest, 'whsec_...');
    $type = $payload->type();  // "user.created"
    $data = $payload->data();
} catch (WebhookException $e) {
    http_response_code(400);
}

XidClient オプション

キー	デフォルト	説明
`issuer`	必須	XID 発行者 URI
`audience`	`null`	expected audience。null は検証をスキップします
`cache`	`null`	JWKS キャッシュ用の PSR-16 CacheInterface
`jwks_ttl`	`3600`	JWKS キャッシュ TTL（秒）
`clock_leeway`	`0`	JWT クロックスキュー許容値（秒）
`cookie_name`	`__xid_session`	トークン取得用のセッション Cookie キー

XidClient メソッド

方式	戻り値	説明
`verifyToken(string $token)`	`Claims`	JWT 文字列を検証します。失敗時にスローします
`authenticateRequest(ServerRequestInterface $request)`	`AuthResult`	PSR-7 リクエストを認証します。スローしません
`verifyWebhook(ServerRequestInterface $request, string $secret)`	`WebhookPayload`	webhook 署名を検証します。失敗時にスローします
`refreshJwks()`	`void`	JWKS キャッシュを強制更新します

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

ES256/RS256 検証に firebase/php-jwt を使用します。HS256 と none アルゴリズムは拒否されます。
authenticateRequest と verifyWebhook には PSR-7 リクエストオブジェクトが必要です。必要に応じて PSR-7 ブリッジでフレームワークネイティブリクエストを変換してください。
例外階層：XidException -> TokenException、JwksException、WebhookException。