Ondertekening & verificatie

badges.ninja publiceert een openbare cryptografische identiteit zodat derden credentials kunnen verifiëren die een digitale handtekening dragen. Dit is de basis voor ondersteuning van Open Badges 3.0 / W3C Verifiable Credentials.

Deze endpoints zijn openbaar en vereisen geen authenticatie. Ze zijn relatief ten opzichte van https://api.badges.ninja.

Uitgever-DID

De uitgeversidentiteit van het platform is de did:web-identifier:

did:web:api.badges.ninja

Volgens de did:web-regels wordt deze omgezet naar het DID-document dat op het onderstaande well-known-pad wordt geserveerd.

DID-document

GET /.well-known/did.json

Geeft het DID-document terug dat de openbare ondertekeningssleutel van de uitgever (een Ed25519 JsonWebKey2020) als zijn assertionMethod blootstelt.

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>"]
}

Het content-type van het antwoord is application/did+json. Het document is cachebaar (het wijzigt alleen bij sleutelrotatie).

JWKS

Voor verifiers die de JWK-Set-discovery verkiezen boven DID-resolutie:

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"
    }
  ]
}

De kid is de RFC 7638-thumbprint van de openbare sleutel en komt overeen met het fragment op de verificationMethod-id van het DID-document.

Verifiable Credential (Open Badges 3.0)

Elke award kan worden opgehaald als Open Badges 3.0 / W3C Verifiable Credential, ondertekend met de bovenstaande uitgeverssleutel.

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

Query	Resultaat
(standaard) of ?format=jwt	Het ondertekende VC-JWT (application/jwt) — te importeren in een OB 3.0-wallet.
?format=json	De niet-ondertekende OpenBadgeCredential-JSON (application/vc+ld+json) — ter inspectie.

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

Het credential is een ["VerifiableCredential", "OpenBadgeCredential"]-getypeerd VC (contexten https://www.w3.org/ns/credentials/v2 en de OB 3.0-context). De issuer.id is did:web:api.badges.ninja, en de achievement, ontvangersidentiteit (gehasht e-mailadres) en uitgifte-/vervaldatums komen uit de award.

Een VC-JWT verifiëren

Het token is een compacte JWS met een EdDSA-handtekening. Om te verifiëren:

1. Splits het JWT in header.payload.signature.
2. Lees kid uit de header — deze verwijst naar het DID-document / JWKS.
3. Haal de openbare sleutel op en verifieer de Ed25519-handtekening over 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"));

Ontvangers kunnen het credential ook ophalen via het Downloaden-menu op hun openbare credentialpagina (Verifiable Credential).

Handtekeningalgoritme

Handtekeningen gebruiken Ed25519 (EdDSA). De privésleutel wordt serverzijdig bewaard en nooit blootgesteld; alleen de bovenstaande openbare sleutel wordt gepubliceerd.

Gehoste verificatie (Open Badges 2.0)

Elk credential is ook vandaag al onafhankelijk verifieerbaar via zijn gehoste Open Badge 2.0-assertie. Zie Openbare verificatie voor de JSON-endpoints van assertie, badge en uitgever, en Delen & verificatie voor de verificatiepagina die de ontvanger ziet.