Потписивање и провера

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 отисак јавног кључа и одговара фрагменту на ID-ју 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 тврдње. Погледајте Јавна провера за JSON крајње тачке тврдње, значке и издаваоца, као и Дељење и провера за страницу провере намењену примаоцу.