Semnare și verificare

badges.ninja publică o identitate criptografică publică pentru ca terții să poată verifica credențialele care poartă o semnătură digitală. Aceasta este fundamentul suportului pentru Open Badges 3.0 / W3C Verifiable Credentials.

Aceste endpoint-uri sunt publice și nu necesită autentificare. Sunt relative la https://api.badges.ninja.

DID-ul emitentului

Identitatea de emitent a platformei este identificatorul did:web:

did:web:api.badges.ninja

Conform regulilor did:web, acesta se rezolvă la documentul DID servit la calea well-known de mai jos.

Documentul DID

GET /.well-known/did.json

Returnează documentul DID care expune cheia publică de semnare a emitentului (o cheie Ed25519 JsonWebKey2020) drept 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>"]
}

Tipul de conținut al răspunsului este application/did+json. Documentul poate fi stocat în cache (se schimbă doar la rotația cheii).

JWKS

Pentru verificatorii care preferă descoperirea prin JWK Set în locul rezolvării 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 este amprenta RFC 7638 a cheii publice și corespunde fragmentului din ID-ul verificationMethod al documentului DID.

Credențială verificabilă (Open Badges 3.0)

Fiecare distincție poate fi obținută ca o Open Badges 3.0 / W3C Verifiable Credential, semnată cu cheia emitentului de mai sus.

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

Interogare	Rezultat
(implicit) sau ?format=jwt	VC-JWT-ul semnat (application/jwt) — importă-l într-un portofel OB 3.0.
?format=json	JSON-ul OpenBadgeCredential nesemnat (application/vc+ld+json) — pentru inspecție.

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

Credențiala este o VC de tip ["VerifiableCredential", "OpenBadgeCredential"] (contextele https://www.w3.org/ns/credentials/v2 și contextul OB 3.0). issuer.id al acesteia este did:web:api.badges.ninja, iar realizarea, identitatea destinatarului (e-mail hash-uit) și datele de emitere/expirare provin din distincție.

Verificarea unui VC-JWT

Token-ul este un JWS compact cu o semnătură EdDSA. Pentru a-l verifica:

1. Împarte JWT-ul în header.payload.signature.
2. Citește kid din antet — acesta indică spre documentul DID / JWKS.
3. Obține cheia publică și verifică semnătura Ed25519 asupra 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"));

Destinatarii pot obține credențiala și din meniul Download de pe pagina publică a credențialei lor (Verifiable Credential).

Algoritmul de semnare

Semnăturile folosesc Ed25519 (EdDSA). Cheia privată este custodiată pe server și nu este niciodată expusă; se publică doar cheia publică de mai sus.

Verificare găzduită (Open Badges 2.0)

Fiecare credențială este de asemenea verificabilă independent și astăzi prin aserțiunea sa găzduită Open Badge 2.0. Vezi Verificare publică pentru endpoint-urile JSON de aserțiune, insignă și emitent, și Partajare și verificare pentru pagina de verificare destinată destinatarului.