sdk/php | XID

SDK de servidor PHP 8.1+ para verificación JWT sin llamadas de red, autenticación de solicitudes PSR-7 y validación de firma de webhook.

Estado

Implementado y verificado localmente. La verificación de ida y vuelta contra un IdP real (obtención de JWKS, firma/verificación de tokens contra una instancia XID en producción) aún no se ha realizado y debe completarse antes del uso en producción.

Instalación

Se requiere PHP 8.1+. Las dependencias principales se obtienen automáticamente con Composer.

composer require xid/xid

Inicio rápido

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

Autenticar una solicitud 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);
}

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

Opciones de XidClient

Clave	Por defecto	Descripción
`issuer`	obligatorio	URI del emisor XID
`audience`	`null`	Audiencia esperada; null omite la validación
`cache`	`null`	CacheInterface PSR-16 para almacenamiento en caché de JWKS
`jwks_ttl`	`3600`	TTL del caché de JWKS en segundos
`clock_leeway`	`0`	Tolerancia de desfase de reloj JWT en segundos
`cookie_name`	`__xid_session`	Clave de cookie de sesión para extraer el token

Métodos de XidClient

Método	Devuelve	Descripción
`verifyToken(string $token)`	`Claims`	Verifica una cadena JWT; lanza excepción al fallar
`authenticateRequest(ServerRequestInterface $request)`	`AuthResult`	Autenticar solicitud PSR-7; no lanza excepciones
`verifyWebhook(ServerRequestInterface $request, string $secret)`	`WebhookPayload`	Valida la firma del webhook; lanza excepción al fallar
`refreshJwks()`	`void`	Forzar actualización del caché de JWKS

Notas de plataforma

Usa firebase/php-jwt para la verificación ES256/RS256. Los algoritmos HS256 y none son rechazados.
Requiere un objeto de solicitud PSR-7 para authenticateRequest y verifyWebhook. Convierte las solicitudes nativas del framework con un bridge PSR-7 si es necesario.
Jerarquía de excepciones: XidException -> TokenException, JwksException, WebhookException.