Signature et vérification

badges.ninja publie une identité cryptographique publique afin que des tiers puissent vérifier les credentials qui portent une signature numérique. C'est le fondement de la prise en charge d'Open Badges 3.0 / W3C Verifiable Credentials.

Ces points de terminaison sont publics et ne nécessitent aucune authentification. Ils sont relatifs à https://api.badges.ninja.

DID de l'émetteur

L'identité d'émetteur de la plateforme est l'identifiant did:web :

did:web:api.badges.ninja

Selon les règles did:web, celui-ci se résout vers le document DID servi au chemin well-known ci-dessous.

Document DID

GET /.well-known/did.json

Renvoie le document DID exposant la clé de signature publique de l'émetteur (une clé Ed25519 JsonWebKey2020) comme son 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>"]
}

Le type de contenu de la réponse est application/did+json. Le document est cacheable (il ne change qu'en cas de rotation de clé).

JWKS

Pour les vérificateurs qui préfèrent la découverte par JWK Set plutôt que la résolution 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"
    }
  ]
}

Le kid est l'empreinte RFC 7638 de la clé publique et correspond au fragment de l'identifiant verificationMethod du document DID.

Verifiable Credential (Open Badges 3.0)

Chaque award peut être récupéré comme Open Badges 3.0 / W3C Verifiable Credential, signé avec la clé d'émetteur ci-dessus.

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

Paramètre de requête	Résultat
(par défaut) ou ?format=jwt	Le VC-JWT signé (application/jwt) — à importer dans un wallet OB 3.0.
?format=json	Le JSON OpenBadgeCredential non signé (application/vc+ld+json) — pour inspection.

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

Le credential est un VC typé ["VerifiableCredential", "OpenBadgeCredential"] (contextes https://www.w3.org/ns/credentials/v2 et le contexte OB 3.0). Son issuer.id est did:web:api.badges.ninja, et l'achievement, l'identité du destinataire (e-mail haché) ainsi que les dates d'émission/expiration proviennent de l'award.

Vérifier un VC-JWT

Le token est un JWS compact avec une signature EdDSA. Pour le vérifier :

1. Découpez le JWT en header.payload.signature.
2. Lisez kid dans l'en-tête — il pointe vers le document DID / JWKS.
3. Récupérez la clé publique et vérifiez la signature Ed25519 sur 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"));

Les destinataires peuvent aussi récupérer le credential depuis le menu Télécharger de leur page publique de credential (Verifiable Credential).

Algorithme de signature

Les signatures utilisent Ed25519 (EdDSA). La clé privée est conservée côté serveur et jamais exposée ; seule la clé publique ci-dessus est publiée.

Vérification hébergée (Open Badges 2.0)

Chaque credential est également vérifiable de manière indépendante dès aujourd'hui via son assertion Open Badge 2.0 hébergée. Voir Vérification publique pour les points de terminaison JSON d'assertion, de badge et d'émetteur, et Partage et vérification pour la page de vérification destinée au destinataire.