İmzalama ve Doğrulama

badges.ninja, üçüncü tarafların dijital imza taşıyan kimlik bilgilerini doğrulayabilmesi için herkese açık bir kriptografik kimlik yayınlar. Bu, Open Badges 3.0 / W3C Verifiable Credentials desteğinin temelidir.

Bu uç noktalar herkese açıktır ve kimlik doğrulaması gerektirmez. https://api.badges.ninja adresine görelidir.

Verici DID'i

Platformun verici kimliği, did:web tanımlayıcısıdır:

did:web:api.badges.ninja

did:web kurallarına göre bu, aşağıdaki iyi bilinen yolda sunulan DID belgesine çözümlenir.

DID Belgesi

GET /.well-known/did.json

Vericinin herkese açık imzalama anahtarını (bir Ed25519 JsonWebKey2020) assertionMethod olarak açığa çıkaran DID belgesini döndürür.

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

Yanıt içerik türü application/did+json'dur. Belge önbelleğe alınabilir (yalnızca anahtar döndürmede değişir).

JWKS

DID çözümlemesi yerine JWK Set keşfini tercih eden doğrulayıcılar için:

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, herkese açık anahtarın RFC 7638 parmak izidir ve DID belgesinin verificationMethod kimliğindeki parçayla eşleşir.

Verifiable Credential (Open Badges 3.0)

Her ödül, yukarıdaki verici anahtarıyla imzalanmış bir Open Badges 3.0 / W3C Verifiable Credential olarak alınabilir.

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

Sorgu	Sonuç
(varsayılan) veya ?format=jwt	İmzalı VC-JWT (application/jwt) — bir OB 3.0 cüzdanına içe aktarın.
?format=json	İmzasız OpenBadgeCredential JSON'u (application/vc+ld+json) — inceleme için.

# İmzalı kimlik bilgisi (VC-JWT)
curl https://api.badges.ninja/certify-badge/award/<guid>/vc

# İnsan tarafından okunabilir kimlik bilgisi JSON'u
curl "https://api.badges.ninja/certify-badge/award/<guid>/vc?format=json"

Kimlik bilgisi, ["VerifiableCredential", "OpenBadgeCredential"] türünde bir VC'dir (https://www.w3.org/ns/credentials/v2 bağlamları ve OB 3.0 bağlamı). issuer.id değeri did:web:api.badges.ninja'dır; başarı, alıcı kimliği (karma e-posta) ve veriliş/son kullanma tarihleri ödülden gelir.

Bir VC-JWT'yi Doğrulama

Belirteç, EdDSA imzasına sahip kompakt bir JWS'dir. Doğrulamak için:

1. JWT'yi header.payload.signature olarak bölün.
2. Başlıktan kid'i okuyun — bu, DID belgesine / JWKS işaret eder.
3. Herkese açık anahtarı getirin ve header.payload üzerindeki Ed25519 imzasını doğrulayın.

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"));

Alıcılar kimlik bilgisini, herkese açık kimlik bilgisi sayfalarındaki Download menüsünden de alabilirler (Verifiable Credential).

İmza Algoritması

İmzalar Ed25519 (EdDSA) kullanır. Özel anahtar sunucu tarafında saklanır ve asla açığa çıkarılmaz; yalnızca yukarıdaki herkese açık anahtar yayınlanır.

Barındırılan Doğrulama (Open Badges 2.0)

Her kimlik bilgisi, barındırılan Open Badge 2.0 onayı aracılığıyla bugün bağımsız olarak da doğrulanabilir. Onay, rozet ve verici JSON uç noktaları için Herkese Açık Doğrulama sayfasına, alıcıya yönelik doğrulama sayfası için Paylaşım ve Doğrulama sayfasına bakın.