KYA for developers: install and integrate the engine

Installation

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

Package: @knowyouragent/verify-core@1.2.0
Size: 83.1 KB, no dependencies
SHA-256: d4ba5f8d928487b396c2565165cfcf04cb758959749093a73a7173da60600d57
npm integrity: sha512-sISUhZZNFhPFQa5kGC6l8oX4zC9MtIGu+lzdC/Yy1m3Aq8yODEX1MtQ8R5nzmpR1FjzTpjzu110X6Y7IBDAmaQ==
Runtimes: Node.js 20 or later and current browsers (tested); other runtimes with Web Crypto are possible but not part of the tests
License: Apache 2.0

The package is built reproducibly with every release; the checksum above is the one of the delivered archive. The file knowyouragent-verify-core-1.2.0.tgz.sha256 lets you compare before installing.

Use in code

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

const report = await verify(evidence, {
  trustedKeys: jwksJson,      // JWKS of the issuers you trust
  statusLists: statusTokens,  // optional: status list tokens
  tsaAnchors: tsaPem,         // optional: root certificates of timestamp authorities
});

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

verify() makes no network requests. The same input with the same options yields the same reportDigest.

Options

Option	Type	Effect
`trustedKeys`	JWKS (JSON) or a list of JWKs	Keys of trusted issuers; without them, signatures are reported as not checked
`statusLists`	Status list tokens (text)	Enables the revocation check offline
`tsaAnchors`	PEM certificates	Trust anchors for RFC 3161 timestamps
`now`	Date or ISO string	Evaluation time for reproducible tests; default is the current time

The verification report

Every call returns a report in the format kya-report/1: verdict (VALID, INVALID, INDETERMINATE), level (KYA-A0 to KYA-A4), the ten checks with status and reason code, the facts read and hashes of input and options. Reason codes are stable and suited for automated evaluation.

Command line

npx kya-verify evidence.json --keys jwks.json --anchors tsa.pem
# exit 0 = valid, 1 = invalid, 2 = indeterminate, 64 = usage error

For accepting agents in a pipeline: GitHub Actions example.

JSON schemas

The formats are published as JSON Schema (draft 2020-12) and included in the package. Every report of the 62 test vectors is checked against them on every release.

kya-report-1.schema.json – verification report
kya-pack-1.schema.json – evidence pack
kya-chain-1.schema.json – receipt chain

Versioning and stability

The package follows Semantic Versioning. New formats and checks raise the minor version.
The meaning of verdicts and levels is tied to the policy version (kya-policy/1.0). It only changes with a new major version.
Reason codes are added, not renamed.
The test vectors are included in the package: @knowyouragent/verify-core/vectors/*.json.

All versions

Issuing instead of verifying

The engine verifies evidence; it does not issue any. For mandates, decisions before execution and receipts there are issuing systems, for example the reference implementation Mandact from the operator of KYA.

For developers