Verificar o recibo assinado de uma decisão

Cada decisão sobre um pedido vem com um recibo assinado que o seu sistema pode verificar sem depender do serviço.

Passo 1: o resumo do pedido

Recalcule SHA-256("AUTHGUARD\0INTENT\0V1\0" ‖ intentJson) sobre os bytes UTF-8 de intentJson exatamente como recebidos (o prefixo tem três bytes NUL). Tem de ser igual a intentDigest.

Passo 2: o resumo do recibo

Confirme receipt.payloadDigestSha256 == SHA-256(receipt.payload).

Passo 3: o conteúdo do recibo

Interprete receipt.payload (schema authguard.intent.decision-receipt, version 1) e confirme:

• intentId, tenantId, clientId e subjectUserId esperados;
• intentDigestSha256 igual ao passo 1;
• decision é approved ou denied;
• factor é passkey ou device (decisão no telemóvel);
• decidedAtEpochSeconds está entre a emissão e a expiração do pedido.

Os SDKs fazem os passos 1 a 3 com verifyIntentDigest e checkReceipt (TypeScript) ou verify_intent_digest e check_receipt (Python).

Passo 4: as assinaturas

receipt.signatureEnvelope tem duas assinaturas, ML-DSA-65 e Ed25519, sobre o domínio intent_decision_receipt, com o identificador do pedido como objeto e receipt.payload como bytes canónicos. Verifique as duas com as chaves públicas da instalação. Nesta fase, o operador entrega essas chaves públicas a pedido, por um canal separado; compare as impressões digitais SHA-256 que lhe forem comunicadas.

Quando verificar

Antes de executar uma operação aprovada, e sempre que precisar de provar a um auditor que a operação foi aprovada por aquela pessoa, com aquele fator, naquele momento.