Signing at Verification

Ang badges.ninja ay naglalathala ng pampublikong cryptographic identity para ma-verify ng mga third party ang mga credential na may dalang digital signature. Ito ang pundasyon para sa suporta ng Open Badges 3.0 / W3C Verifiable Credentials.

Ang mga endpoint na ito ay pampubliko at hindi nangangailangan ng authentication. Ang mga ito ay relative sa https://api.badges.ninja.

Issuer DID

Ang issuer identity ng platform ay ang did:web identifier:

did:web:api.badges.ninja

Ayon sa mga panuntunan ng did:web, nire-resolve ito sa DID document na inihahain sa well-known path sa ibaba.

DID Document

GET /.well-known/did.json

Ibinabalik ang DID document na naglalantad sa pampublikong signing key ng issuer (isang Ed25519 JsonWebKey2020) bilang assertionMethod nito.

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

Ang content type ng response ay application/did+json. Ang document ay cacheable (nagbabago lang ito kapag may key rotation).

JWKS

Para sa mga verifier na mas gusto ang JWK Set discovery kaysa DID resolution:

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

Ang kid ay ang RFC 7638 thumbprint ng public key at tumutugma sa fragment ng verificationMethod id ng DID document.

Verifiable Credential (Open Badges 3.0)

Ang bawat award ay maaaring makuha bilang isang Open Badges 3.0 / W3C Verifiable Credential, na naka-sign gamit ang issuer key sa itaas.

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

Query	Resulta
(default) o ?format=jwt	Ang naka-sign na VC-JWT (application/jwt) — i-import sa isang OB 3.0 wallet.
?format=json	Ang unsigned na OpenBadgeCredential JSON (application/vc+ld+json) — para sa inspeksyon.

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

Ang credential ay isang ["VerifiableCredential", "OpenBadgeCredential"] na typed VC (mga context na https://www.w3.org/ns/credentials/v2 at ang OB 3.0 context). Ang issuer.id nito ay did:web:api.badges.ninja, at ang achievement, recipient identity (hashed email), at mga petsa ng pag-isyu/pag-expire ay nagmumula sa award.

Pag-verify ng VC-JWT

Ang token ay isang compact JWS na may EdDSA signature. Para i-verify:

1. Hatiin ang JWT sa header.payload.signature.
2. Basahin ang kid mula sa header — tumuturo ito sa DID document / JWKS.
3. Kunin ang public key at i-verify ang Ed25519 signature sa 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"));

Maaari ring kunin ng mga recipient ang credential mula sa Download menu sa kanilang public credential page (Verifiable Credential).

Signature Algorithm

Ang mga signature ay gumagamit ng Ed25519 (EdDSA). Ang private key ay iniingatan sa server-side at hindi kailanman inilalantad; ang public key lamang sa itaas ang inilalathala.

Hosted Verification (Open Badges 2.0)

Ang bawat credential ay independent ding ma-verify ngayon sa pamamagitan ng hosted Open Badge 2.0 assertion nito. Tingnan ang Public Verification para sa mga assertion, badge, at issuer JSON endpoint, at ang Sharing at Verification para sa recipient-facing verification page.