Υπογραφή & Επαλήθευση

Το badges.ninja δημοσιεύει μια δημόσια κρυπτογραφική ταυτότητα ώστε τρίτα μέρη να μπορούν να επαληθεύουν διαπιστευτήρια που φέρουν ψηφιακή υπογραφή. Αυτό είναι το θεμέλιο για την υποστήριξη Open Badges 3.0 / W3C Verifiable Credentials.

Αυτά τα endpoints είναι δημόσια και δεν απαιτούν πιστοποίηση. Είναι σχετικά ως προς το https://api.badges.ninja.

DID Εκδότη

Η ταυτότητα εκδότη της πλατφόρμας είναι το αναγνωριστικό did:web:

did:web:api.badges.ninja

Σύμφωνα με τους κανόνες του did:web, αυτό αναλύεται στο έγγραφο DID που εξυπηρετείται στη γνωστή διαδρομή παρακάτω.

Έγγραφο DID

GET /.well-known/did.json

Επιστρέφει το έγγραφο DID που εκθέτει το δημόσιο κλειδί υπογραφής του εκδότη (ένα Ed25519 JsonWebKey2020) ως το 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>"]
}

Ο τύπος περιεχομένου της απόκρισης είναι application/did+json. Το έγγραφο είναι προσωρινά αποθηκεύσιμο (αλλάζει μόνο κατά την εναλλαγή κλειδιού).

JWKS

Για επαληθευτές που προτιμούν την ανακάλυψη JWK Set αντί για ανάλυση 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 είναι το αποτύπωμα RFC 7638 του δημόσιου κλειδιού και ταιριάζει με το θραύσμα στο αναγνωριστικό verificationMethod του εγγράφου DID.

Verifiable Credential (Open Badges 3.0)

Κάθε βραβείο μπορεί να ανακτηθεί ως Open Badges 3.0 / W3C Verifiable Credential, υπογεγραμμένο με το παραπάνω κλειδί εκδότη.

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

Query	Αποτέλεσμα
(προεπιλογή) ή ?format=jwt	Το υπογεγραμμένο VC-JWT (application/jwt) — εισαγωγή σε ένα πορτοφόλι OB 3.0.
?format=json	Το ανυπόγραφο JSON OpenBadgeCredential (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"

Το διαπιστευτήριο είναι ένα VC τύπου ["VerifiableCredential", "OpenBadgeCredential"] (πλαίσια https://www.w3.org/ns/credentials/v2 και το πλαίσιο OB 3.0). Το issuer.id του είναι did:web:api.badges.ninja, και το επίτευγμα, η ταυτότητα του παραλήπτη (κατακερματισμένο email) και οι ημερομηνίες έκδοσης/λήξης προέρχονται από το βραβείο.

Επαλήθευση ενός VC-JWT

Το token είναι ένα συμπαγές JWS με υπογραφή EdDSA. Για να επαληθεύσετε:

1. Χωρίστε το JWT σε header.payload.signature.
2. Διαβάστε το kid από την κεφαλίδα — δείχνει προς το έγγραφο DID / JWKS.
3. Ανακτήστε το δημόσιο κλειδί και επαληθεύστε την υπογραφή Ed25519 πάνω στο 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"));

Οι παραλήπτες μπορούν επίσης να λάβουν το διαπιστευτήριο από το μενού Download στη δημόσια σελίδα διαπιστευτηρίου τους (Verifiable Credential).

Αλγόριθμος Υπογραφής

Οι υπογραφές χρησιμοποιούν Ed25519 (EdDSA). Το ιδιωτικό κλειδί φυλάσσεται στην πλευρά του διακομιστή και δεν εκτίθεται ποτέ· δημοσιεύεται μόνο το παραπάνω δημόσιο κλειδί.

Φιλοξενούμενη Επαλήθευση (Open Badges 2.0)

Κάθε διαπιστευτήριο είναι επίσης ανεξάρτητα επαληθεύσιμο σήμερα μέσω της φιλοξενούμενης βεβαίωσης Open Badge 2.0 του. Δείτε Δημόσια Επαλήθευση για τα endpoints JSON βεβαίωσης, εμβλήματος και εκδότη, και Κοινοποίηση & Επαλήθευση για τη σελίδα επαλήθευσης που βλέπει ο παραλήπτης.