Signering og verifisering

badges.ninja publiserer en offentlig kryptografisk identitet slik at tredjeparter kan verifisere bevis som bærer en digital signatur. Dette er grunnlaget for støtte for Open Badges 3.0 / W3C Verifiable Credentials.

Disse endepunktene er offentlige og krever ingen autentisering. De er relative til https://api.badges.ninja.

Utsteder-DID

Plattformens utstederidentitet er did:web-identifikatoren:

did:web:api.badges.ninja

Etter did:web-reglene løses dette til DID-dokumentet som serveres på den velkjente stien nedenfor.

DID-dokument

GET /.well-known/did.json

Returnerer DID-dokumentet som eksponerer utstederens offentlige signeringsnøkkel (en Ed25519 JsonWebKey2020) som sin 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 innholdstype er application/did+json. Dokumentet kan bufres (det endres kun ved nøkkelrotasjon).

JWKS

For verifikatorer som foretrekker JWK Set-oppdagelse fremfor DID-opplø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-fingeravtrykket av den offentlige nøkkelen og matcher fragmentet på DID-dokumentets verificationMethod-id.

Verifiserbart bevis (Open Badges 3.0)

Hvert bevis kan hentes som et Open Badges 3.0 / W3C Verifiable Credential, signert med utstedernøkkelen ovenfor.

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

Spørring	Resultat
(standard) eller ?format=jwt	Det signerte VC-JWT (application/jwt) — importer til en OB 3.0-lommebok.
?format=json	Den usignerte OpenBadgeCredential-JSON-en (application/vc+ld+json) — for inspeksjon.

# 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 prestasjonen, mottakeridentiteten (hashet e-post) og utstedelses-/utløpsdatoene kommer fra beviset.

Verifisere et VC-JWT

Tokenet er en kompakt JWS med en EdDSA-signatur. Slik verifiserer du:

1. Del JWT-en opp i header.payload.signature.
2. Les kid fra headeren — den peker inn i DID-dokumentet / JWKS.
3. Hent den offentlige nøkkelen og verifiser 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"));

Mottakere kan også hente beviset fra menyen Download på sin offentlige bevisside (Verifiable Credential).

Signaturalgoritme

Signaturer bruker Ed25519 (EdDSA). Den private nøkkelen oppbevares på serversiden og eksponeres aldri; kun den offentlige nøkkelen ovenfor publiseres.

Hostet verifisering (Open Badges 2.0)

Hvert bevis er også uavhengig verifiserbart i dag via sin hostede Open Badge 2.0-assertion. Se Offentlig verifisering for assertion-, badge- og utsteder-JSON-endepunktene, og Deling og verifisering for den mottakervendte verifiseringssiden.