Firma e verifica

badges.ninja pubblica un'identità crittografica pubblica affinché terze parti possano verificare le credenziali che recano una firma digitale. Questa è la base per il supporto di Open Badges 3.0 / W3C Verifiable Credentials.

Questi endpoint sono pubblici e non richiedono autenticazione. Sono relativi a https://api.badges.ninja.

DID dell'emittente

L'identità di emittente della piattaforma è l'identificatore did:web:

did:web:api.badges.ninja

Secondo le regole did:web, questo si risolve nel documento DID servito al percorso well-known qui sotto.

Documento DID

GET /.well-known/did.json

Restituisce il documento DID che espone la chiave di firma pubblica dell'emittente (una chiave Ed25519 JsonWebKey2020) come suo 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>"]
}

Il content type della risposta è application/did+json. Il documento è memorizzabile nella cache (cambia solo alla rotazione della chiave).

JWKS

Per i verificatori che preferiscono la discovery tramite JWK Set alla risoluzione 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"
    }
  ]
}

Il kid è il thumbprint RFC 7638 della chiave pubblica e corrisponde al frammento sull'id verificationMethod del documento DID.

Verifiable Credential (Open Badges 3.0)

Ogni award può essere recuperato come Open Badges 3.0 / W3C Verifiable Credential, firmato con la chiave dell'emittente sopra indicata.

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

Query	Risultato
(predefinito) o ?format=jwt	Il VC-JWT firmato (application/jwt) — da importare in un wallet OB 3.0.
?format=json	Il JSON OpenBadgeCredential non firmato (application/vc+ld+json) — per l'ispezione.

# 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"

La credenziale è un VC tipizzato ["VerifiableCredential", "OpenBadgeCredential"] (contesti https://www.w3.org/ns/credentials/v2 e il contesto OB 3.0). Il suo issuer.id è did:web:api.badges.ninja, e l'achievement, l'identità del destinatario (email con hash) e le date di rilascio/scadenza provengono dall'award.

Verificare un VC-JWT

Il token è un JWS compatto con una firma EdDSA. Per verificarlo:

1. Suddividi il JWT in header.payload.signature.
2. Leggi kid dall'header — punta al documento DID / JWKS.
3. Recupera la chiave pubblica e verifica la firma Ed25519 su 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"));

I destinatari possono anche ottenere la credenziale dal menu Scarica sulla loro pagina pubblica della credenziale (Verifiable Credential).

Algoritmo di firma

Le firme usano Ed25519 (EdDSA). La chiave privata è custodita lato server e mai esposta; viene pubblicata solo la chiave pubblica sopra indicata.

Verifica ospitata (Open Badges 2.0)

Ogni credenziale è inoltre verificabile in modo indipendente già oggi tramite la sua assertion Open Badge 2.0 ospitata. Vedi Verifica pubblica per gli endpoint JSON di assertion, badge ed emittente, e Condivisione e verifica per la pagina di verifica rivolta al destinatario.