Podpisywanie i weryfikacja

badges.ninja publikuje publiczną tożsamość kryptograficzną, aby strony trzecie mogły weryfikować poświadczenia opatrzone podpisem cyfrowym. Jest to podstawa obsługi Open Badges 3.0 / W3C Verifiable Credentials.

Te endpointy są publiczne i nie wymagają uwierzytelnienia. Są względne do https://api.badges.ninja.

DID wystawcy

Tożsamość wystawcy platformy to identyfikator did:web:

did:web:api.badges.ninja

Zgodnie z regułami did:web, rozwiązuje się on do dokumentu DID serwowanego pod ścieżką well-known poniżej.

Dokument DID

GET /.well-known/did.json

Zwraca dokument DID ujawniający publiczny klucz podpisujący wystawcy (Ed25519 JsonWebKey2020) jako jego 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>"]
}

Typ zawartości odpowiedzi to application/did+json. Dokument jest buforowalny (zmienia się tylko przy rotacji klucza).

JWKS

Dla weryfikatorów, którzy wolą wykrywanie JWK Set od rozwiązywania 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"
    }
  ]
}

kid to odcisk palca klucza publicznego według RFC 7638 i pasuje do fragmentu w identyfikatorze verificationMethod dokumentu DID.

Poświadczenie weryfikowalne (Open Badges 3.0)

Każde wyróżnienie można pobrać jako Open Badges 3.0 / W3C Verifiable Credential, podpisane kluczem wystawcy powyżej.

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

Zapytanie	Wynik
(domyślnie) lub ?format=jwt	Podpisany VC-JWT (application/jwt) — zaimportuj do portfela OB 3.0.
?format=json	Niepodpisany JSON OpenBadgeCredential (application/vc+ld+json) — do wglądu.

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

Poświadczenie to VC typu ["VerifiableCredential", "OpenBadgeCredential"] (konteksty https://www.w3.org/ns/credentials/v2 oraz kontekst OB 3.0). Jego issuer.id to did:web:api.badges.ninja, a osiągnięcie, tożsamość odbiorcy (zahaszowany e-mail) oraz daty wystawienia/wygaśnięcia pochodzą z wyróżnienia.

Weryfikacja VC-JWT

Token to kompaktowy JWS z podpisem EdDSA. Aby zweryfikować:

1. Podziel JWT na header.payload.signature.
2. Odczytaj kid z nagłówka — wskazuje on na dokument DID / JWKS.
3. Pobierz klucz publiczny i zweryfikuj podpis Ed25519 nad 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"));

Odbiorcy mogą też pobrać poświadczenie z menu Download na swojej publicznej stronie poświadczenia (Verifiable Credential).

Algorytm podpisu

Podpisy używają Ed25519 (EdDSA). Klucz prywatny jest przechowywany po stronie serwera i nigdy nie jest ujawniany; publikowany jest tylko klucz publiczny powyżej.

Weryfikacja hostowana (Open Badges 2.0)

Każde poświadczenie jest też dziś niezależnie weryfikowalne poprzez swój hostowany wpis asercji Open Badge 2.0. Zobacz Weryfikacja publiczna dla endpointów JSON asercji, odznaki i wystawcy oraz Udostępnianie i weryfikacja dla strony weryfikacji skierowanej do odbiorcy.