Ký & xác minh

badges.ninja công bố một danh tính mật mã công khai để các bên thứ ba có thể xác minh những chứng chỉ mang chữ ký số. Đây là nền tảng cho việc hỗ trợ Open Badges 3.0 / W3C Verifiable Credentials.

Các điểm cuối này là công khai và không yêu cầu xác thực. Chúng có địa chỉ tương đối so với https://api.badges.ninja.

DID của tổ chức cấp

Danh tính của tổ chức cấp trên nền tảng là định danh did:web:

did:web:api.badges.ninja

Theo các quy tắc của did:web, định danh này phân giải thành tài liệu DID được phục vụ tại đường dẫn well-known bên dưới.

Tài liệu DID

GET /.well-known/did.json

Trả về tài liệu DID để lộ khóa ký công khai của tổ chức cấp (một khóa Ed25519 JsonWebKey2020) làm assertionMethod của nó.

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

Kiểu nội dung của phản hồi là application/did+json. Tài liệu có thể được lưu vào bộ nhớ đệm (nó chỉ thay đổi khi xoay khóa).

JWKS

Dành cho các bên xác minh ưa thích việc khám phá JWK Set hơn là phân giải 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 là dấu vân tay theo RFC 7638 của khóa công khai và khớp với đoạn fragment trên id verificationMethod của tài liệu DID.

Verifiable Credential (Open Badges 3.0)

Mọi giải thưởng đều có thể được truy xuất dưới dạng một Open Badges 3.0 / W3C Verifiable Credential, được ký bằng khóa của tổ chức cấp ở trên.

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

Truy vấn	Kết quả
(mặc định) hoặc ?format=jwt	VC-JWT đã ký (application/jwt) — nhập vào một ví OB 3.0.
?format=json	JSON OpenBadgeCredential chưa ký (application/vc+ld+json) — để kiểm tra.

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

Chứng chỉ là một VC có kiểu ["VerifiableCredential", "OpenBadgeCredential"] (với các context https://www.w3.org/ns/credentials/v2 và context OB 3.0). Trường issuer.id của nó là did:web:api.badges.ninja, còn thành tích, danh tính người nhận (email đã băm) và ngày cấp/hết hạn đều đến từ giải thưởng.

Xác minh một VC-JWT

Token là một JWS dạng nén với chữ ký EdDSA. Để xác minh:

1. Tách JWT thành header.payload.signature.
2. Đọc kid từ header — nó trỏ vào tài liệu DID / JWKS.
3. Lấy khóa công khai và xác minh chữ ký Ed25519 trên 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"));

Người nhận cũng có thể lấy chứng chỉ từ menu Download trên trang chứng chỉ công khai của họ (Verifiable Credential).

Thuật toán ký

Chữ ký sử dụng Ed25519 (EdDSA). Khóa riêng được lưu giữ ở phía máy chủ và không bao giờ bị để lộ; chỉ có khóa công khai ở trên được công bố.

Xác minh được lưu trữ (Open Badges 2.0)

Mọi chứng chỉ cũng có thể được xác minh độc lập ngay hôm nay thông qua khẳng định (assertion) Open Badge 2.0 được lưu trữ của nó. Xem Xác minh công khai để biết các điểm cuối JSON cho assertion, huy hiệu và tổ chức cấp, và Chia sẻ & xác minh để biết trang xác minh hướng tới người nhận.