Signatura i verificació

badges.ninja publica una identitat criptogràfica pública perquè tercers puguin verificar les credencials que porten una signatura digital. Aquesta és la base del suport per a Open Badges 3.0 / W3C Verifiable Credentials.

Aquests endpoints són públics i no requereixen autenticació. Són relatius a https://api.badges.ninja.

DID de l'emissor

La identitat d'emissor de la plataforma és l'identificador did:web:

did:web:api.badges.ninja

Segons les regles de did:web, això es resol al document DID servit a la ruta well-known de més avall.

Document DID

GET /.well-known/did.json

Retorna el document DID que exposa la clau pública de signatura de l'emissor (una JsonWebKey2020 Ed25519) com el 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>"]
}

El tipus de contingut de la resposta és application/did+json. El document és cacheable (només canvia en rotar la clau).

JWKS

Per als verificadors que prefereixen el descobriment per JWK Set en lloc de la resolució 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"
    }
  ]
}

El kid és el thumbprint RFC 7638 de la clau pública i coincideix amb el fragment de l'id de verificationMethod del document DID.

Credencial verificable (Open Badges 3.0)

Cada credencial es pot obtenir com una Open Badges 3.0 / W3C Verifiable Credential, signada amb la clau d'emissor de més amunt.

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

Consulta	Resultat
(per defecte) o ?format=jwt	El VC-JWT signat (application/jwt) — importa'l a una cartera OB 3.0.
?format=json	El JSON OpenBadgeCredential sense signar (application/vc+ld+json) — per a inspecció.

# 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 credencial és una VC amb tipus ["VerifiableCredential", "OpenBadgeCredential"] (contextos https://www.w3.org/ns/credentials/v2 i el context OB 3.0). El seu issuer.id és did:web:api.badges.ninja, i l'assoliment, la identitat del destinatari (correu amb hash) i les dates d'emissió/caducitat provenen de la credencial.

Verificar un VC-JWT

El token és un JWS compacte amb una signatura EdDSA. Per verificar-lo:

1. Divideix el JWT en header.payload.signature.
2. Llegeix el kid de la capçalera — apunta al document DID / JWKS.
3. Obtén la clau pública i verifica la signatura 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"));

Els destinataris també poden obtenir la credencial des del menú Download a la seva pàgina pública de credencial (Verifiable Credential).

Algorisme de signatura

Les signatures fan servir Ed25519 (EdDSA). La clau privada es custodia al servidor i mai s'exposa; només es publica la clau pública de més amunt.

Verificació allotjada (Open Badges 2.0)

Cada credencial també és verificable de manera independent avui mateix mitjançant la seva assertion allotjada d'Open Badge 2.0. Consulta Verificació pública per als endpoints JSON d'assertion, insígnia i emissor, i Compartició i verificació per a la pàgina de verificació orientada al destinatari.