KYA für Entwickler: Prüfkern installieren und einbinden

Installation

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

Paket: @knowyouragent/verify-core@1.2.0
Grösse: 83.1 KB, keine Abhängigkeiten
SHA-256: d4ba5f8d928487b396c2565165cfcf04cb758959749093a73a7173da60600d57
npm-Integrität: sha512-sISUhZZNFhPFQa5kGC6l8oX4zC9MtIGu+lzdC/Yy1m3Aq8yODEX1MtQ8R5nzmpR1FjzTpjzu110X6Y7IBDAmaQ==
Laufzeiten: Node.js ab 20 und aktuelle Browser (getestet); andere Laufzeiten mit Web Crypto sind möglich, aber nicht Teil der Tests
Lizenz: Apache 2.0

Das Paket wird bei jedem Release reproduzierbar gebaut; die Prüfsumme oben ist die des ausgelieferten Archivs. Die Datei knowyouragent-verify-core-1.2.0.tgz.sha256 erlaubt den Abgleich vor der Installation.

Verwendung im Code

import { verify } from "@knowyouragent/verify-core";

const report = await verify(evidence, {
  trustedKeys: jwksJson,      // JWKS der Aussteller, denen Sie vertrauen
  statusLists: statusTokens,  // optional: Statuslisten-Token
  tsaAnchors: tsaPem,         // optional: Wurzelzertifikate der Zeitstempeldienste
});

if (report.verdict === "INVALID") throw new Error(report.checks.find((c) => c.status === "INVALID").reason);
console.log(report.assurance, report.reportDigest);

verify() stellt keine Netzwerkanfragen. Dieselbe Eingabe mit denselben Optionen ergibt denselben reportDigest.

Optionen

Option	Typ	Wirkung
`trustedKeys`	JWKS (JSON) oder Liste von JWKs	Schlüssel vertrauenswürdiger Aussteller; ohne sie gelten Signaturen als nicht geprüft
`statusLists`	Statuslisten-Token (Text)	Ermöglicht die Widerrufsprüfung offline
`tsaAnchors`	PEM-Zertifikate	Vertrauensanker für RFC-3161-Zeitstempel
`now`	Date oder ISO-Zeichenkette	Prüfzeitpunkt für reproduzierbare Tests; sonst die aktuelle Zeit

Der Prüfbericht

Jeder Aufruf liefert einen Bericht im Format kya-report/1: Urteil (VALID, INVALID, INDETERMINATE), Stufe (KYA-A0 bis KYA-A4), die zehn Prüfschritte mit Status und Begründungscode, gelesene Angaben sowie Hashes von Eingabe und Optionen. Begründungscodes sind stabil und eignen sich für automatische Auswertung.

Kommandozeile

npx kya-verify nachweis.json --keys jwks.json --anchors tsa.pem
# Exit 0 = gültig, 1 = ungültig, 2 = unbestimmt, 64 = falscher Aufruf

Für die Abnahme von Agenten in der Pipeline: Beispiel für GitHub Actions.

JSON-Schemas

Die Formate sind als JSON Schema (Draft 2020-12) veröffentlicht und im Paket enthalten. Jeder Bericht der 62 Testvektoren wird bei jedem Release dagegen geprüft.

kya-report-1.schema.json – Prüfbericht
kya-pack-1.schema.json – Nachweispaket
kya-chain-1.schema.json – Beleg-Kette

Versionierung und Stabilität

Das Paket folgt Semantic Versioning. Neue Formate und Prüfungen erhöhen die Nebenversion.
Die Bedeutung von Urteilen und Stufen hängt an der Policy-Version (kya-policy/1.0). Sie ändert sich nur mit einer neuen Hauptversion.
Begründungscodes werden ergänzt, nicht umbenannt.
Die Testvektoren sind im Paket enthalten: @knowyouragent/verify-core/vectors/*.json.

Alle Versionen

Ausstellen statt prüfen

Der Prüfkern prüft Nachweise, er stellt keine aus. Für Mandate, Entscheide vor der Ausführung und Belege gibt es ausstellende Systeme, zum Beispiel die Referenzimplementierung Mandact vom Betreiber von KYA.

Für Entwickler