Penanda Tanganan & Verifikasi

badges.ninja menerbitkan identitas kriptografis publik sehingga pihak ketiga dapat memverifikasi kredensial yang membawa tanda tangan digital. Ini adalah fondasi untuk dukungan Open Badges 3.0 / W3C Verifiable Credentials.

Endpoint-endpoint ini bersifat publik dan tidak memerlukan autentikasi. Semuanya relatif terhadap https://api.badges.ninja.

DID Penerbit

Identitas penerbit platform adalah pengenal did:web:

did:web:api.badges.ninja

Berdasarkan aturan did:web, ini di-resolve ke dokumen DID yang disajikan pada jalur well-known di bawah.

Dokumen DID

GET /.well-known/did.json

Mengembalikan dokumen DID yang mengekspos kunci penanda tangan publik penerbit (sebuah Ed25519 JsonWebKey2020) sebagai assertionMethod-nya.

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

Tipe konten respons adalah application/did+json. Dokumen ini dapat di-cache (hanya berubah saat rotasi kunci).

JWKS

Untuk verifikator yang lebih menyukai penemuan JWK Set daripada resolusi 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 adalah thumbprint RFC 7638 dari kunci publik dan cocok dengan fragmen pada id verificationMethod dokumen DID.

Verifiable Credential (Open Badges 3.0)

Setiap penghargaan dapat diambil sebagai Open Badges 3.0 / W3C Verifiable Credential, ditandatangani dengan kunci penerbit di atas.

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

Query	Hasil
(default) atau ?format=jwt	VC-JWT bertanda tangan (application/jwt) — impor ke dompet OB 3.0.
?format=json	JSON OpenBadgeCredential tanpa tanda tangan (application/vc+ld+json) — untuk inspeksi.

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

Kredensial ini adalah VC bertipe ["VerifiableCredential", "OpenBadgeCredential"] (konteks https://www.w3.org/ns/credentials/v2 dan konteks OB 3.0). issuer.id-nya adalah did:web:api.badges.ninja, dan pencapaian, identitas penerima (email ter-hash), serta tanggal terbit/kedaluwarsa berasal dari penghargaan.

Memverifikasi VC-JWT

Token ini adalah JWS ringkas dengan tanda tangan EdDSA. Untuk memverifikasi:

1. Pisahkan JWT menjadi header.payload.signature.
2. Baca kid dari header — ia menunjuk ke dokumen DID / JWKS.
3. Ambil kunci publik dan verifikasi tanda tangan Ed25519 atas 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"));

Penerima juga dapat mengambil kredensial dari menu Download pada halaman kredensial publik mereka (Verifiable Credential).

Algoritme Tanda Tangan

Tanda tangan menggunakan Ed25519 (EdDSA). Kunci privat dikustodikan di sisi server dan tidak pernah diekspos; hanya kunci publik di atas yang dipublikasikan.

Verifikasi Terhosting (Open Badges 2.0)

Setiap kredensial juga dapat diverifikasi secara independen saat ini melalui asersi Open Badge 2.0 terhostingnya. Lihat Verifikasi Publik untuk endpoint JSON asersi, lencana, dan penerbit, serta Berbagi & Verifikasi untuk halaman verifikasi yang menghadap penerima.