Penandatanganan & Pengesahan

badges.ninja menerbitkan identiti kriptografi awam supaya pihak ketiga boleh mengesahkan kredensial yang membawa tandatangan digital. Ini ialah asas untuk sokongan Open Badges 3.0 / W3C Verifiable Credentials.

Titik akhir ini adalah awam dan tidak memerlukan pengesahan. Ia relatif kepada https://api.badges.ninja.

DID Pengeluar

Identiti pengeluar platform ialah pengecam did:web:

did:web:api.badges.ninja

Menurut peraturan did:web, ini menyelesai kepada dokumen DID yang disajikan di laluan well-known di bawah.

Dokumen DID

GET /.well-known/did.json

Mengembalikan dokumen DID yang mendedahkan kunci penandatanganan awam pengeluar (satu 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>"]
}

Jenis kandungan respons ialah application/did+json. Dokumen ini boleh dicache (ia berubah hanya apabila kunci diputar).

JWKS

Untuk pengesah yang lebih suka penemuan JWK Set berbanding 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 ialah cap ibu jari RFC 7638 bagi kunci awam dan sepadan dengan serpihan pada ID verificationMethod dokumen DID.

Verifiable Credential (Open Badges 3.0)

Setiap award boleh diperoleh sebagai Open Badges 3.0 / W3C Verifiable Credential, ditandatangani dengan kunci pengeluar di atas.

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

Pertanyaan	Keputusan
(lalai) atau ?format=jwt	VC-JWT yang ditandatangani (application/jwt) — import ke dalam dompet OB 3.0.
?format=json	JSON OpenBadgeCredential tidak ditandatangani (application/vc+ld+json) — untuk pemeriksaan.

# 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 ialah VC bertaip ["VerifiableCredential", "OpenBadgeCredential"] (konteks https://www.w3.org/ns/credentials/v2 dan konteks OB 3.0). issuer.id-nya ialah did:web:api.badges.ninja, dan pencapaian, identiti penerima (e-mel bercincang), serta tarikh keluaran/luput datang daripada award.

Mengesahkan VC-JWT

Token ialah JWS padat dengan tandatangan EdDSA. Untuk mengesahkan:

1. Pisahkan JWT kepada header.payload.signature.
2. Baca kid daripada pengepala — ia menunjuk ke dalam dokumen DID / JWKS.
3. Dapatkan kunci awam dan sahkan tandatangan Ed25519 ke 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 boleh memperoleh kredensial daripada menu Download pada halaman kredensial awam mereka (Verifiable Credential).

Algoritma Tandatangan

Tandatangan menggunakan Ed25519 (EdDSA). Kunci persendirian disimpan di sisi pelayan dan tidak pernah didedahkan; hanya kunci awam di atas yang diterbitkan.

Pengesahan Terhos (Open Badges 2.0)

Setiap kredensial juga boleh disahkan secara bebas hari ini melalui pernyataan Open Badge 2.0 terhosnya. Lihat Pengesahan Awam untuk titik akhir JSON pernyataan, lencana dan pengeluar, serta Perkongsian & Pengesahan untuk halaman pengesahan yang menghadap penerima.