Signatur & Verifizierung

badges.ninja veröffentlicht eine öffentliche kryptografische Identität, damit Dritte Credentials verifizieren können, die eine digitale Signatur tragen. Dies ist die Grundlage für die Unterstützung von Open Badges 3.0 / W3C Verifiable Credentials.

Diese Endpunkte sind öffentlich und erfordern keine Authentifizierung. Sie sind relativ zu https://api.badges.ninja.

Aussteller-DID

Die Ausstelleridentität der Plattform ist der did:web-Identifier:

did:web:api.badges.ninja

Gemäß den did:web-Regeln wird dieser zum DID-Dokument aufgelöst, das unter dem folgenden Well-known-Pfad bereitgestellt wird.

DID-Dokument

GET /.well-known/did.json

Gibt das DID-Dokument zurück, das den öffentlichen Signaturschlüssel des Ausstellers (einen Ed25519 JsonWebKey2020) als seine assertionMethod offenlegt.

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

Der Content-Type der Antwort ist application/did+json. Das Dokument ist cachebar (es ändert sich nur bei einer Schlüsselrotation).

JWKS

Für Verifizierer, die die JWK-Set-Discovery der DID-Auflösung vorziehen:

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

Die kid ist der RFC-7638-Thumbprint des öffentlichen Schlüssels und stimmt mit dem Fragment der verificationMethod-ID des DID-Dokuments überein.

Verifiable Credential (Open Badges 3.0)

Jeder Award kann als Open Badges 3.0 / W3C Verifiable Credential abgerufen werden, signiert mit dem obigen Ausstellerschlüssel.

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

Query	Ergebnis
(Standard) oder ?format=jwt	Das signierte VC-JWT (application/jwt) — in eine OB-3.0-Wallet importierbar.
?format=json	Das unsignierte OpenBadgeCredential-JSON (application/vc+ld+json) — zur Inspektion.

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

Das Credential ist ein ["VerifiableCredential", "OpenBadgeCredential"]-typisiertes VC (Kontexte https://www.w3.org/ns/credentials/v2 und der OB-3.0-Kontext). Seine issuer.id ist did:web:api.badges.ninja, und Achievement, Empfängeridentität (gehashte E-Mail) sowie Ausstellungs-/Ablaufdaten stammen aus dem Award.

Ein VC-JWT verifizieren

Das Token ist ein kompaktes JWS mit einer EdDSA-Signatur. Zum Verifizieren:

1. Teile das JWT in header.payload.signature auf.
2. Lies kid aus dem Header — es verweist in das DID-Dokument / JWKS.
3. Rufe den öffentlichen Schlüssel ab und verifiziere die Ed25519-Signatur über 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"));

Empfänger können das Credential auch über das Download-Menü auf ihrer öffentlichen Credential-Seite (Verifiable Credential) abrufen.

Signaturalgorithmus

Signaturen verwenden Ed25519 (EdDSA). Der private Schlüssel wird serverseitig verwahrt und niemals offengelegt; nur der obige öffentliche Schlüssel wird veröffentlicht.

Gehostete Verifizierung (Open Badges 2.0)

Jedes Credential ist außerdem schon heute unabhängig über seine gehostete Open-Badge-2.0-Assertion verifizierbar. Siehe Öffentliche Verifizierung für die JSON-Endpunkte von Assertion, Badge und Aussteller sowie Teilen & Verifizierung für die empfängerseitige Verifizierungsseite.