sdk/php | XID

SDK serveur PHP 8.1+ pour la vérification JWT sans réseau,l'authentification des requêtes PSR-7 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.

Installer

PHP 8.1+ requis. Les dépendances principales sont récupéréesautomatiquement par Composer.

composer require xid/xid

Démarrage rapide

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

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

Vérifier le 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);
}

Options XidClient

Clé	Défaut	Description
`issuer`	requis	URI d’émetteur XID
`audience`	`null`	Audience attendue ; null ignore la validation
`cache`	`null`	CacheInterface PSR-16 pour la mise en cache JWKS
`jwks_ttl`	`3600`	TTL du cache JWKS en secondes
`clock_leeway`	`0`	Tolérance au décalage d’horloge JWT en secondes
`cookie_name`	`__xid_session`	Clé du cookie de session pour l’extraction du jeton

Méthodes XidClient

Méthode	Retourne	Description
`verifyToken(string $token)`	`Claims`	Vérifier la chaîne JWT ; lève une exception en cas d’échec
`authenticateRequest(ServerRequestInterface $request)`	`AuthResult`	Authentifier une requête PSR-7 ; ne lève pas d’exception
`verifyWebhook(ServerRequestInterface $request, string $secret)`	`WebhookPayload`	Valider la signature webhook ; lève une exception en cas d’échec
`refreshJwks()`	`void`	Forcer le rafraîchissement du cache JWKS

Notes de plateforme

Utilise firebase/php-jwt pour la vérification ES256/RS256. Lesalgorithmes HS256 et none sont rejetés.
Nécessite un objet de requête PSR-7 pour authenticateRequest etverifyWebhook. Convertissez les requêtes natives du framework avecun pont PSR-7 si nécessaire.
Hiérarchie d’exceptions : XidException -> TokenException,JwksException, WebhookException.