Podpisovanie a overovanie

badges.ninja zverejňuje verejnú kryptografickú identitu, aby tretie strany mohli overiť poverovacie listiny, ktoré nesú digitálny podpis. Toto je základ pre podporu Open Badges 3.0 / W3C Verifiable Credentials.

Tieto koncové body sú verejné a nevyžadujú žiadnu autentifikáciu. Sú relatívne voči https://api.badges.ninja.

DID vydavateľa

Identita vydavateľa platformy je identifikátor did:web:

did:web:api.badges.ninja

Podľa pravidiel did:web sa toto rozlíši na DID dokument obsluhovaný na nižšie uvedenej well-known ceste.

DID dokument

GET /.well-known/did.json

Vráti DID dokument sprístupňujúci verejný podpisový kľúč vydavateľa (Ed25519 JsonWebKey2020) ako jeho 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>"]
}

Typ obsahu odpovede je application/did+json. Dokument je cachovateľný (mení sa iba pri rotácii kľúča).

JWKS

Pre verifikátory, ktoré uprednostňujú objavovanie JWK Set pred rozlíšením 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 je RFC 7638 thumbprint verejného kľúča a zhoduje sa s fragmentom v id verificationMethod DID dokumentu.

Verifiable Credential (Open Badges 3.0)

Každé ocenenie je možné získať ako Open Badges 3.0 / W3C Verifiable Credential, podpísané vyššie uvedeným kľúčom vydavateľa.

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

Query	Výsledok
(predvolené) alebo ?format=jwt	Podpísané VC-JWT (application/jwt) — importujte do OB 3.0 peňaženky.
?format=json	Nepodpísaný OpenBadgeCredential JSON (application/vc+ld+json) — na kontrolu.

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

Poverovacia listina je VC typu ["VerifiableCredential", "OpenBadgeCredential"] (kontexty https://www.w3.org/ns/credentials/v2 a kontext OB 3.0). Jej issuer.id je did:web:api.badges.ninja a úspech, identita príjemcu (hashovaný e-mail) a dátumy vydania/expirácie pochádzajú z ocenenia.

Overovanie VC-JWT

Token je kompaktný JWS s podpisom EdDSA. Na overenie:

1. Rozdeľte JWT na header.payload.signature.
2. Prečítajte kid z hlavičky — ukazuje do DID dokumentu / JWKS.
3. Získajte verejný kľúč a overte podpis Ed25519 nad 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"));

Príjemcovia môžu poverovaciu listinu tiež získať z ponuky Download na svojej verejnej stránke poverovacej listiny (Verifiable Credential).

Algoritmus podpisu

Podpisy používajú Ed25519 (EdDSA). Súkromný kľúč je uschovaný na strane servera a nikdy sa nesprístupňuje; zverejnený je iba vyššie uvedený verejný kľúč.

Hostované overovanie (Open Badges 2.0)

Každá poverovacia listina je aj dnes nezávisle overiteľná prostredníctvom svojej hostovanej Open Badge 2.0 assertion. Pozri Verejné overovanie pre JSON koncové body assertion, odznaku a vydavateľa a Zdieľanie a overovanie pre overovaciu stránku určenú príjemcom.