Podpis a ověření

badges.ninja zveřejňuje veřejnou kryptografickou identitu, aby třetí strany mohly ověřovat přihlašovací údaje nesoucí digitální podpis. To je základ podpory Open Badges 3.0 / W3C Verifiable Credentials.

Tyto endpointy jsou veřejné a nevyžadují autentizaci. Jsou relativní k https://api.badges.ninja.

DID vydavatele

Identita vydavatele platformy je identifikátor did:web:

did:web:api.badges.ninja

Podle pravidel did:web se to překládá na DID dokument obsluhovaný na well-known cestě níže.

DID dokument

GET /.well-known/did.json

Vrací DID dokument, který vystavuje veřejný podpisový klíč vydavatele (Ed25519 JsonWebKey2020) jako svůj 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>"]
}

Typ obsahu odpovědi je application/did+json. Dokument je uložitelný do mezipaměti (mění se pouze při rotaci klíče).

JWKS

Pro ověřovatele, kteří upřednostňují objevování JWK Set před rozlišením 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 je otisk veřejného klíče podle RFC 7638 a odpovídá fragmentu v identifikátoru verificationMethod DID dokumentu.

Ověřitelný přihlašovací údaj (Open Badges 3.0)

Každé ocenění lze načíst jako Open Badges 3.0 / W3C Verifiable Credential, podepsané klíčem vydavatele výše.

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

Dotaz	Výsledek
(výchozí) nebo ?format=jwt	Podepsaný VC-JWT (application/jwt) — importujte do peněženky OB 3.0.
?format=json	Nepodepsaný JSON OpenBadgeCredential (application/vc+ld+json) — k prohlédnutí.

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

Přihlašovací údaj je VC typu ["VerifiableCredential", "OpenBadgeCredential"] (kontexty https://www.w3.org/ns/credentials/v2 a kontext OB 3.0). Jeho issuer.id je did:web:api.badges.ninja a úspěch, identita příjemce (hashovaný e-mail) a data vydání/vypršení pocházejí z ocenění.

Ověření VC-JWT

Token je kompaktní JWS s podpisem EdDSA. Chcete-li jej ověřit:

1. Rozdělte JWT na header.payload.signature.
2. Přečtěte kid z hlavičky — odkazuje na DID dokument / JWKS.
3. Načtěte veřejný klíč a ověřte podpis Ed25519 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"));

Příjemci si mohou přihlašovací údaj také stáhnout z nabídky Download na své veřejné stránce přihlašovacích údajů (Verifiable Credential).

Algoritmus podpisu

Podpisy používají Ed25519 (EdDSA). Soukromý klíč je uchováván na straně serveru a nikdy není vystaven; zveřejňuje se pouze veřejný klíč výše.

Hostované ověření (Open Badges 2.0)

Každý přihlašovací údaj je dnes také nezávisle ověřitelný prostřednictvím svého hostovaného assertion záznamu Open Badge 2.0. Viz Veřejné ověření pro JSON endpointy assertion, odznaku a vydavatele a Sdílení a ověření pro ověřovací stránku určenou příjemci.