sdk/php | XID

SDK de servidor PHP 8.1+ para verificação JWT sem rede, autenticaçãode requisições PSR-7 e validação de assinatura de webhook.

Estado

Implementado e verificado localmente. A verificação de ida e voltacom um IdP real (busca de JWKS, assinatura/verificação de tokencontra uma instância XID ativa) ainda não foi realizada e deve serconcluída antes do uso em produção.

Instalar

PHP 8.1+ obrigatório. As dependências principais são baixadasautomaticamente pelo Composer.

composer require xid/xid

Início 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);
}

Autentica uma requisição 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);
}

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

Opções do XidClient

Chave	Padrão	Descrição
`issuer`	obrigatório	URI do emissor XID
`audience`	`null`	Audiência esperada; null ignora a validação
`cache`	`null`	CacheInterface PSR-16 para cache de JWKS
`jwks_ttl`	`3600`	TTL do cache JWKS em segundos
`clock_leeway`	`0`	Tolerância de desvio de relógio JWT em segundos
`cookie_name`	`__xid_session`	Chave de cookie de sessão para extração de token

Métodos do XidClient

Método	Retornos	Descrição
`verifyToken(string $token)`	`Claims`	Verifica string JWT; lança exceção em caso de falha
`authenticateRequest(ServerRequestInterface $request)`	`AuthResult`	Autentica requisição PSR-7; não lança exceções
`verifyWebhook(ServerRequestInterface $request, string $secret)`	`WebhookPayload`	Valida a assinatura do webhook; lança exceção em caso de falha
`refreshJwks()`	`void`	Forçar atualização do cache JWKS

Notas da plataforma

Usa firebase/php-jwt para verificação ES256/RS256. Osalgoritmos HS256 e none são rejeitados.
Requer um objeto de requisição PSR-7 para authenticateRequeste verifyWebhook. Converta requisições nativas do framework comuma ponte PSR-7 se necessário.
Hierarquia de exceções: XidException -> TokenException,JwksException, WebhookException.