Prüfkern in Node.js einbinden: Nachweise im Backend prüfen

Das Wichtigste in Kürze

Der Prüfkern läuft in Node.js ab Version 20 ohne Laufzeitabhängigkeiten und ohne Netzwerkzugriff.
verify() liefert Urteil, Stufe, zehn Prüfschritte und einen nachrechenbaren reportDigest.
INDETERMINATE bedeutet fehlenden Nachweis und ist kein Erfolg.

Paket installieren

Der Prüfkern hat keine Laufzeitabhängigkeiten und braucht Node.js ab Version 20. Installieren Sie das Paket direkt von knowyouragent.ch:

npm install https://knowyouragent.ch/downloads/knowyouragent-verify-core-1.2.0.tgz

Neben dem Paket liegt seine Prüfsumme als Datei mit der Endung .sha256; vergleichen Sie sie vor dem Einsatz in Produktion.

Vertrauen hinterlegen

Legen Sie fest, welchen Ausstellern Sie vertrauen: deren öffentliche Schlüssel als JWKS, die aktuellen Statuslisten für den Widerruf und, für die höchste Stufe, die Anker der Zeitstempelstellen als PEM. Der Prüfkern lädt nichts selbst aus dem Netz; was Sie nicht hinterlegen, gilt als nicht belegt.

verify() aufrufen

Die Funktion verify() nimmt den Nachweis als Text oder Bytes und die Optionen now, trustedKeys, statusLists und tsaAnchors:

import { readFile } from "node:fs/promises";
import { verify } from "@knowyouragent/verify-core";

const report = await verify(await readFile("evidence.json", "utf8"), {
  trustedKeys: await readFile("issuer-jwks.json", "utf8"),
  statusLists: [await readFile("status-list.jwt", "utf8")],
});

console.log(report.verdict, report.assuranceLabel, report.reportDigest);
for (const check of report.checks) console.log(check.id, check.status, check.reason ?? "");
if (report.verdict !== "VALID") process.exitCode = 1;

Ergebnis auswerten

Das Urteil lautet VALID, INVALID oder INDETERMINATE, dazu kommen die Stufe, alle zehn Prüfschritte mit Status und Begründungscode sowie ein reportDigest, mit dem sich das Ergebnis später nachrechnen lässt. Die Bedeutung jedes Codes steht in der Fehlerreferenz. Werten Sie INDETERMINATE nicht als Erfolg: Es heisst, dass ein Nachweis fehlt, etwa eine Statusliste.

In den Ablauf einbauen

Rufen Sie verify() dort auf, wo Sie über eine Handlung entscheiden, etwa vor der Annahme einer Bestellung, und speichern Sie den Bericht oder mindestens den reportDigest zusammen mit dem Vorgang. Die Prüfung läuft lokal und deterministisch; dieselben Eingaben ergeben denselben Digest. Das Verhalten des Prüfkerns ist durch die öffentlichen Testvektoren festgelegt.

Fehler beheben

Die häufigsten Ergebnisse bei der ersten Integration und ihre Bedeutung:

issuer_key_not_trusted: Der Schlüssel des Ausstellers fehlt in trustedKeys. Hinterlegen Sie das JWKS des Ausstellers.
status_list_not_provided: Das Mandat verweist auf eine Statusliste, die nicht übergeben wurde.
unsupported_alg: Der Algorithmus wird nicht unterstützt; unterstützt sind ES256, ES384, EdDSA, RS256 und PS256.

Alle Codes erklärt die Fehlerreferenz.

Häufige Fragen

Funktioniert der Prüfkern auch mit TypeScript?

Ja. Das Paket bringt Typdefinitionen mit, darunter VerifyOptions, Report und Check.

Kann ich den Prüfkern in einer Serverless-Funktion einsetzen?

Ja. Er hat keine Laufzeitabhängigkeiten, nutzt WebCrypto und braucht keinen Netzwerkzugriff.

Wie lege ich den Prüfzeitpunkt fest?

Mit der Option now, als Datum, Zeitstempel oder ISO-Text. So lassen sich frühere Prüfungen exakt wiederholen.

Wie gross ist das Paket?

Das Paket ist klein und hat keine Laufzeitabhängigkeiten. Es enthält neben dem Code die JSON-Schemas, die Testvektoren und die Kommandozeile.

Kann ich den Prüfkern im Browser meiner eigenen Anwendung nutzen?

Ja. Der Prüfkern ist dasselbe Programm, das auf der Prüfseite läuft; mit einem Bundler lässt er sich in Webanwendungen einbinden.

Wie verarbeite ich binäre Nachweise wie Zeitstempel?

Übergeben Sie sie als Uint8Array statt als Text. verify() akzeptiert beides und erkennt das Format selbst.

Was ist reportDigest genau?

Ein Hash über den kanonischen Bericht. Wer dieselben Eingaben mit demselben Prüfzeitpunkt prüft, erhält denselben Wert und kann so belegen, dass ein Ergebnis unverändert ist.

Quellen

@knowyouragent/verify-core (Paket): https://knowyouragent.ch/downloads/knowyouragent-verify-core-1.2.0.tgz
KYA-Prüfprofil: https://knowyouragent.ch/standard/pruefprofil