Підпис і перевірка

badges.ninja публікує відкриту криптографічну ідентичність, щоб треті сторони могли перевіряти облікові дані, що несуть цифровий підпис. Це основа підтримки Open Badges 3.0 / W3C Verifiable Credentials.

Ці ендпоінти публічні й не вимагають автентифікації. Вони вказані відносно https://api.badges.ninja.

DID емітента

Ідентичність емітента платформи — це ідентифікатор did:web:

did:web:api.badges.ninja

За правилами did:web він розв’язується в DID-документ, що обслуговується за well-known-шляхом нижче.

DID-документ

GET /.well-known/did.json

Повертає DID-документ, що розкриває відкритий ключ підпису емітента (Ed25519 JsonWebKey2020) як його 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>"]
}

Тип вмісту відповіді — application/did+json. Документ кешується (він змінюється лише під час ротації ключа).

JWKS

Для верифікаторів, які надають перевагу виявленню JWK Set замість розв’язання 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 — це відбиток відкритого ключа за RFC 7638, що збігається з фрагментом в ідентифікаторі verificationMethod DID-документа.

Перевіряні облікові дані (Open Badges 3.0)

Кожну нагороду можна отримати як Open Badges 3.0 / W3C Verifiable Credential, підписану ключем емітента вище.

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

Запит	Результат
(за замовчуванням) або ?format=jwt	Підписаний VC-JWT (application/jwt) — імпортуйте в гаманець OB 3.0.
?format=json	Непідписаний JSON OpenBadgeCredential (application/vc+ld+json) — для перегляду.

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

Облікові дані — це VC з типом ["VerifiableCredential", "OpenBadgeCredential"] (контексти https://www.w3.org/ns/credentials/v2 та контекст OB 3.0). Його issuer.id — did:web:api.badges.ninja, а досягнення, ідентичність отримувача (хешований email) та дати видачі/завершення беруться з нагороди.

Перевірка VC-JWT

Токен — це компактний JWS з підписом EdDSA. Щоб перевірити:

1. Розділіть JWT на header.payload.signature.
2. Прочитайте kid із заголовка — він вказує на DID-документ / JWKS.
3. Отримайте відкритий ключ і перевірте підпис Ed25519 над 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"));

Отримувачі також можуть узяти облікові дані з меню Download на своїй публічній сторінці облікових даних (Verifiable Credential).

Алгоритм підпису

Підписи використовують Ed25519 (EdDSA). Закритий ключ зберігається на боці сервера й ніколи не розкривається; публікується лише відкритий ключ вище.

Хостована перевірка (Open Badges 2.0)

Кожні облікові дані також сьогодні незалежно перевіряні через свій хостований assertion-запис Open Badge 2.0. Див. Публічна перевірка для ендпоінтів JSON assertion, значка та емітента, а також Поширення й перевірка для сторінки перевірки, орієнтованої на отримувача.