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

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, значка и эмитента, а также Публикация и проверка для страницы проверки, ориентированной на получателя.