Signering och verifiering

badges.ninja publicerar en offentlig kryptografisk identitet så att tredje part kan verifiera intyg som bär en digital signatur. Detta är grunden för stödet för Open Badges 3.0 / W3C Verifiable Credentials.

Dessa slutpunkter är offentliga och kräver ingen autentisering. De är relativa till https://api.badges.ninja.

Utfärdar-DID

Plattformens utfärdaridentitet är did:web-identifieraren:

did:web:api.badges.ninja

Enligt did:web-reglerna löses detta till DID-dokumentet som serveras på den välkända sökvägen nedan.

DID-dokument

GET /.well-known/did.json

Returnerar DID-dokumentet som exponerar utfärdarens offentliga signeringsnyckel (en Ed25519 JsonWebKey2020) som dess 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 innehållstyp är application/did+json. Dokumentet är cachebart (det ändras endast vid nyckelrotation).

JWKS

För verifierare som föredrar JWK Set-upptäckt framför DID-upplö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 är RFC 7638-tumavtrycket av den offentliga nyckeln och matchar fragmentet på DID-dokumentets verificationMethod-id.

Verifierbart intyg (Open Badges 3.0)

Varje utmärkelse kan hämtas som ett Open Badges 3.0 / W3C Verifiable Credential, signerat med utfärdarnyckeln ovan.

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

Fråga	Resultat
(standard) eller ?format=jwt	Det signerade VC-JWT (application/jwt) — importera till en OB 3.0-plånbok.
?format=json	Det osignerade OpenBadgeCredential-JSON (application/vc+ld+json) — för 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"

Intyget är ett ["VerifiableCredential", "OpenBadgeCredential"]-typat VC (kontexter https://www.w3.org/ns/credentials/v2 och OB 3.0-kontexten). Dess issuer.id är did:web:api.badges.ninja, och prestationen, mottagaridentiteten (hashad e-post) och utfärdande-/utgångsdatumen kommer från utmärkelsen.

Verifiera ett VC-JWT

Token är en kompakt JWS med en EdDSA-signatur. För att verifiera:

1. Dela upp JWT:n i header.payload.signature.
2. Läs kid från headern — den pekar in i DID-dokumentet / JWKS.
3. Hämta den offentliga nyckeln och verifiera Ed25519-signaturen över 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"));

Mottagare kan också hämta intyget från menyn Download på sin offentliga intygssida (Verifiable Credential).

Signaturalgoritm

Signaturer använder Ed25519 (EdDSA). Den privata nyckeln förvaras på serversidan och exponeras aldrig; endast den offentliga nyckeln ovan publiceras.

Värdbaserad verifiering (Open Badges 2.0)

Varje intyg är även oberoende verifierbart idag via sitt värdbaserade Open Badge 2.0-påstående. Se Offentlig verifiering för påstående-, märkes- och utfärdar-JSON-slutpunkterna, och Delning och verifiering för den mottagarvända verifieringssidan.