HVTracker Trust Credential Specification

1. Abstract

This document defines the Trust Credential: a machine-readable record by which HVTracker attests the evidence-weighted trust of an open-source AI agent. The credential lets a consumer — including another agent (agent-to-agent, A2A) — decide whether to trust an agent before interacting with it.

The key words MUST, MUST NOT, SHOULD, and MAY are to be interpreted as described in RFC 2119.

2. Terminology

Issuer

The trust authority that produces credentials. For this specification the issuer is hvtracker.net.

Subject

The AI agent a credential describes, identified by its source repository and HVTracker slug.

Consumer

Any party — human, tool, or agent — that reads a credential to make a trust decision.

3. Discovery

A consumer SHOULD begin at the authority descriptor https://hvtracker.net/.well-known/hvtracker.json, which declares the issuer, the methodology, and the endpoint templates.

An agent's credential is retrieved from https://hvtracker.net/data/agents/{slug}.json under the trust_credential key. The full registry is available at https://hvtracker.net/data/latest.json.

4. Credential Format

A Trust Credential is a JSON object with the following members:

{
  "spec": "https://hvtracker.net/spec/trust-credential/v0.2",
  "version": "0.2",
  "issuer": "hvtracker.net",
  "subject": { "repo": "owner/name", "slug": "name", "agent_url": "https://hvtracker.net/agents/name" },
  "methodology_version": "v3.2",
  "issued_at": "2026-06-18T00:00:00Z",
  "expires_at": "2026-06-25T00:00:00Z",
  "trust_score": 0-100,
  "confidence": 0.0-1.0,
  "evidence_grade": "A|B|C|D",
  "dimensions": { "safety": n, "identity": n, "transparency": n, "maintenance": n, "adoption": n },
  "listing_status": "listed|legacy|delisted|...",
  "evidence_hash": "<sha256-hex>",
  "signature": "<base64-ed25519, or null if the build had no key>"
}

A consumer MUST treat confidence as a first-class factor: a high trust_score with low confidence reflects thin evidence and SHOULD NOT be relied upon for high-stakes interactions.

5. Verification

A credential is signed with Ed25519 and verified offline: remove the signature member, serialize the remainder as JSON with sorted keys, separators (",",":"), and ensure_ascii=false, then verify the base64 signature against the issuer public key published at /.well-known/hvtracker.json. A consumer MUST reject a credential whose signature does not verify, and SHOULD reject one whose methodology_version it does not recognize.

The evidence_hash is a SHA-256 over the canonical score-bearing fields, binding the score to its evidence snapshot. A consumer MUST treat confidence as first-class, and MAY additionally reproduce the score from public signals per the methodology (an implementation conforming to the methodology MUST land within 0.1 points). A null signature means the issuing build had no signing key; such a credential SHOULD be verified by reproduction only.

6. Revocation and Freshness

Each credential carries issued_at and expires_at. A consumer MUST reject a credential after its expires_at and SHOULD prefer the freshest available. A listing_status of delisted MUST be treated as revocation regardless of score.

7. Signing

Credentials are signed with Ed25519. The issuer public key (base64, raw 32 bytes) is published at /.well-known/hvtracker.json under trust_credential.public_key; the signature is a detached signature over the canonical credential (Section 5). Key rotation re-publishes the public key, so a consumer SHOULD fetch the current key from the authority descriptor rather than pinning it.

8. Versioning

This specification uses vMAJOR.MINOR versioning. Published versions remain accessible at their versioned URLs and MUST NOT be modified after publication.