Potpisivanje i provjera

badges.ninja objavljuje javni kriptografski identitet kako bi treće strane mogle provjeriti vjerodajnice koje nose digitalni potpis. To je temelj podrške za Open Badges 3.0 / W3C Verifiable Credentials.

Ovi su endpointi javni i ne zahtijevaju autentifikaciju. Relativni su na https://api.badges.ninja.

DID izdavatelja

Identitet izdavatelja platforme je did:web identifikator:

did:web:api.badges.ninja

Prema pravilima did:web, on se razrješava na DID dokument koji se poslužuje na well-known putanji ispod.

DID dokument

GET /.well-known/did.json

Vraća DID dokument koji izlaže javni ključ za potpisivanje izdavatelja (Ed25519 JsonWebKey2020) kao svoj 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>"]
}

Tip sadržaja odgovora je application/did+json. Dokument se može predmemorirati (mijenja se samo pri rotaciji ključa).

JWKS

Za verifikatore koji preferiraju otkrivanje putem JWK Seta umjesto razrješavanja DID-a:

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 otisak javnog ključa i odgovara fragmentu na ID-u verificationMethod DID dokumenta.

Provjerljiva vjerodajnica (Open Badges 3.0)

Svaka se nagrada može dohvatiti kao Open Badges 3.0 / W3C Verifiable Credential, potpisana ključem izdavatelja iznad.

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

Upit	Rezultat
(zadano) ili ?format=jwt	Potpisani VC-JWT (application/jwt) — uvezite u OB 3.0 novčanik.
?format=json	Nepotpisani OpenBadgeCredential JSON (application/vc+ld+json) — za pregled.

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

Vjerodajnica je VC tipa ["VerifiableCredential", "OpenBadgeCredential"] (konteksti https://www.w3.org/ns/credentials/v2 i OB 3.0 kontekst). Njezin issuer.id je did:web:api.badges.ninja, a postignuće, identitet primatelja (hеširana e-pošta) te datumi izdavanja/isteka dolaze iz nagrade.

Provjera VC-JWT-a

Token je kompaktni JWS s EdDSA potpisom. Za provjeru:

1. Podijelite JWT na header.payload.signature.
2. Pročitajte kid iz zaglavlja — pokazuje na DID dokument / JWKS.
3. Dohvatite javni ključ i provjerite Ed25519 potpis 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"));

Primatelji vjerodajnicu mogu preuzeti i iz izbornika Download na svojoj javnoj stranici vjerodajnice (Verifiable Credential).

Algoritam potpisivanja

Potpisi koriste Ed25519 (EdDSA). Privatni ključ čuva se na strani poslužitelja i nikada se ne izlaže; objavljuje se samo javni ključ iznad.

Poslužena provjera (Open Badges 2.0)

Svaka je vjerodajnica danas neovisno provjerljiva i putem svoje poslužene Open Badge 2.0 tvrdnje. Pogledajte Javna provjera za JSON endpointe tvrdnje, bedža i izdavatelja te Dijeljenje i provjera za stranicu provjere namijenjenu primatelju.