서명 및 검증

badges.ninja는 공개 암호학적 신원을 게시하여 제3자가 디지털 서명이 포함된 크리덴셜을 검증할 수 있도록 합니다. 이는 Open Badges 3.0 / W3C Verifiable Credentials 지원의 기반입니다.

이 엔드포인트들은 공개되어 있으며 인증이 필요 없습니다. 이들은 https://api.badges.ninja 를 기준으로 합니다.

발급자 DID

플랫폼의 발급자 신원은 did:web 식별자입니다:

did:web:api.badges.ninja

did:web 규칙에 따라, 이것은 아래의 well-known 경로에서 제공되는 DID 문서로 확인됩니다.

DID 문서

GET /.well-known/did.json

발급자의 공개 서명 키(Ed25519 JsonWebKey2020)를 assertionMethod로 노출하는 DID 문서를 반환합니다.

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>"]
}

응답 콘텐츠 타입은 application/did+json 입니다. 이 문서는 캐시할 수 있습니다(키 교체 시에만 변경됨).

JWKS

DID 확인보다 JWK Set 디스커버리를 선호하는 검증자를 위해:

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는 공개 키의 RFC 7638 지문이며, DID 문서의 verificationMethod id에 있는 프래그먼트와 일치합니다.

검증 가능한 크리덴셜(Open Badges 3.0)

모든 어워드는 위의 발급자 키로 서명된 Open Badges 3.0 / W3C Verifiable Credential로 조회할 수 있습니다.

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

쿼리	결과
(기본값) 또는 ?format=jwt	서명된 VC-JWT(application/jwt)——OB 3.0 지갑으로 가져오기.
?format=json	서명되지 않은 OpenBadgeCredential JSON(application/vc+ld+json)——검토용.

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

이 크리덴셜은 ["VerifiableCredential", "OpenBadgeCredential"] 타입의 VC입니다(컨텍스트는 https://www.w3.org/ns/credentials/v2 와 OB 3.0 컨텍스트). 그 issuer.id는 did:web:api.badges.ninja 이며, 성취, 수신자 신원(해시된 이메일), 발급/만료 날짜는 어워드에서 가져옵니다.

VC-JWT 검증

이 토큰은 EdDSA 서명을 가진 컴팩트 JWS입니다. 검증하려면:

1. JWT를 header.payload.signature 로 분할합니다.
2. header에서 kid를 읽습니다——이것은 DID 문서 / JWKS를 가리킵니다.
3. 공개 키를 가져와 header.payload에 대한 Ed25519 서명을 검증합니다.

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"));

수신자는 공개 크리덴셜 페이지의 Download 메뉴에서도 크리덴셜을 받을 수 있습니다(Verifiable Credential).

서명 알고리즘

서명은 Ed25519(EdDSA)를 사용합니다. 개인 키는 서버 측에서 보관되며 절대 노출되지 않습니다. 위의 공개 키만 게시됩니다.

호스팅 검증(Open Badges 2.0)

모든 크리덴셜은 오늘날에도 호스팅된 Open Badge 2.0 어서션을 통해 독립적으로 검증할 수 있습니다. 어서션, 배지, 발급자 JSON 엔드포인트는 공개 검증을, 수신자 대상 검증 페이지는 공유 및 검증을 참조하세요.