Подписване и проверка

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	Неподписаният OpenBadgeCredential JSON (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, а постижението, идентичността на получателя (хеширан имейл) и датите на издаване/изтичане идват от отличието.

Проверка на 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)

Всяко удостоверение е също независимо проверимо и днес чрез своята хоствана Open Badge 2.0 assertion. Вижте Публична проверка за JSON крайните точки на assertion, значка и издател, както и Споделяне и проверка за страницата за проверка, насочена към получателя.