Signering og verificering

badges.ninja offentliggør en offentlig kryptografisk identitet, så tredjeparter kan verificere beviser, der bærer en digital signatur. Dette er fundamentet for understøttelse af Open Badges 3.0 / W3C Verifiable Credentials.

Disse endpoints er offentlige og kræver ingen godkendelse. De er relative til https://api.badges.ninja.

Udsteder-DID

Platformens udstederidentitet er did:web-identifikatoren:

did:web:api.badges.ninja

Efter did:web-reglerne opløses dette til DID-dokumentet, der leveres på den velkendte sti nedenfor.

DID-dokument

GET /.well-known/did.json

Returnerer DID-dokumentet, der eksponerer udstederens offentlige signeringsnøgle (en Ed25519 JsonWebKey2020) som dens 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>"]
}

Svarets indholdstype er application/did+json. Dokumentet kan caches (det ændres kun ved nøglerotation).

JWKS

For verifikatorer, der foretrækker JWK Set-opdagelse frem for DID-opløsning:

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 er RFC 7638-fingeraftrykket af den offentlige nøgle og matcher fragmentet på DID-dokumentets verificationMethod-id.

Verificerbart bevis (Open Badges 3.0)

Hvert bevis kan hentes som et Open Badges 3.0 / W3C Verifiable Credential, signeret med udstedernøglen ovenfor.

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

Query	Resultat
(standard) eller ?format=jwt	Det signerede VC-JWT (application/jwt) — importér til en OB 3.0-wallet.
?format=json	Det usignerede OpenBadgeCredential-JSON (application/vc+ld+json) — til inspektion.

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

Beviset er et ["VerifiableCredential", "OpenBadgeCredential"]-typet VC (kontekster https://www.w3.org/ns/credentials/v2 og OB 3.0-konteksten). Dets issuer.id er did:web:api.badges.ninja, og præstationen, modtageridentiteten (hashet e-mail) og udstedelses-/udløbsdatoerne kommer fra beviset.

Verificering af et VC-JWT

Tokenet er en kompakt JWS med en EdDSA-signatur. For at verificere:

1. Del JWT'en op i header.payload.signature.
2. Læs kid fra headeren — den peger ind i DID-dokumentet / JWKS.
3. Hent den offentlige nøgle og verificér Ed25519-signaturen over 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"));

Modtagere kan også hente beviset fra menuen Download på deres offentlige bevisside (Verifiable Credential).

Signaturalgoritme

Signaturer bruger Ed25519 (EdDSA). Den private nøgle opbevares på serversiden og eksponeres aldrig; kun den offentlige nøgle ovenfor offentliggøres.

Hostet verificering (Open Badges 2.0)

Hvert bevis kan også verificeres uafhængigt i dag via sit hostede Open Badge 2.0-assertion. Se Offentlig verificering for assertion-, badge- og udsteder-JSON-endpoints, og Deling og verificering for den modtagervendte verificeringsside.