Assinatura e verificação

O badges.ninja publica uma identidade criptográfica pública para que terceiros possam verificar credenciais que carregam uma assinatura digital. Essa é a base do suporte a Open Badges 3.0 / W3C Verifiable Credentials.

Estes endpoints são públicos e não exigem autenticação. Eles são relativos a https://api.badges.ninja.

DID do emissor

A identidade de emissor da plataforma é o identificador did:web:

did:web:api.badges.ninja

Pelas regras do did:web, isso é resolvido para o documento DID servido no caminho well-known abaixo.

Documento DID

GET /.well-known/did.json

Retorna o documento DID que expõe a chave pública de assinatura do emissor (uma JsonWebKey2020 Ed25519) como seu assertionMethod.

curl https://api.badges.ninja/.well-known/did.json

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:web:api.badges.ninja",
  "verificationMethod": [
    {
      "id": "did:web:api.badges.ninja#<kid>",
      "type": "JsonWebKey2020",
      "controller": "did:web:api.badges.ninja",
      "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "<base64url>" }
    }
  ],
  "assertionMethod": ["did:web:api.badges.ninja#<kid>"],
  "authentication": ["did:web:api.badges.ninja#<kid>"]
}

O tipo de conteúdo da resposta é application/did+json. O documento é cacheável (só muda na rotação da chave).

JWKS

Para verificadores que preferem a descoberta por JWK Set em vez da resolução DID:

GET /.well-known/jwks.json

curl https://api.badges.ninja/.well-known/jwks.json

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "<base64url>",
      "kid": "<thumbprint>",
      "alg": "EdDSA",
      "use": "sig"
    }
  ]
}

O kid é o thumbprint RFC 7638 da chave pública e corresponde ao fragmento no id do verificationMethod do documento DID.

Credencial verificável (Open Badges 3.0)

Cada credencial pode ser obtida como uma Open Badges 3.0 / W3C Verifiable Credential, assinada com a chave de emissor acima.

GET /certify-badge/award/{guid}/vc

Consulta	Resultado
(padrão) ou ?format=jwt	O VC-JWT assinado (application/jwt) — importe para uma carteira OB 3.0.
?format=json	O JSON OpenBadgeCredential não assinado (application/vc+ld+json) — para inspeção.

# Signed credential (VC-JWT)
curl https://api.badges.ninja/certify-badge/award/<guid>/vc

# Human-readable credential JSON
curl "https://api.badges.ninja/certify-badge/award/<guid>/vc?format=json"

A credencial é uma VC com tipo ["VerifiableCredential", "OpenBadgeCredential"] (contextos https://www.w3.org/ns/credentials/v2 e o contexto OB 3.0). Seu issuer.id é did:web:api.badges.ninja, e a conquista, a identidade do destinatário (e-mail com hash) e as datas de emissão/expiração vêm da credencial.

Verificando um VC-JWT

O token é um JWS compacto com uma assinatura EdDSA. Para verificar:

1. Divida o JWT em header.payload.signature.
2. Leia o kid do cabeçalho — ele aponta para o documento DID / JWKS.
3. Obtenha a chave pública e verifique a assinatura Ed25519 sobre header.payload.

import crypto from "node:crypto";

const [h, p, s] = jwt.split(".");
const jwks = await (await fetch("https://api.badges.ninja/.well-known/jwks.json")).json();
const jwk = jwks.keys[0];
const pub = crypto.createPublicKey({ key: jwk, format: "jwk" });
const ok = crypto.verify(null, Buffer.from(`${h}.${p}`), pub, Buffer.from(s, "base64url"));

Os destinatários também podem obter a credencial no menu Download na sua página pública de credencial (Verifiable Credential).

Algoritmo de assinatura

As assinaturas usam Ed25519 (EdDSA). A chave privada é custodiada no servidor e nunca é exposta; apenas a chave pública acima é publicada.

Verificação hospedada (Open Badges 2.0)

Cada credencial também é verificável de forma independente hoje por meio da sua assertion hospedada de Open Badge 2.0. Consulte Verificação pública para os endpoints JSON de assertion, distintivo e emissor, e Compartilhamento e verificação para a página de verificação voltada ao destinatário.