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.1",
  "version": "0.1",
  "issuer": "hvtracker.net",
  "subject": { "repo": "owner/name", "slug": "name", "agent_url": "https://hvtracker.net/agents/name" },
  "methodology_version": "v3.0",
  "issued_at": "2026-05-28 12:00 UTC",
  "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|...",
  "signature": null
}

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

Until signed credentials are issued (Section 7), a credential is verified by reproduction: the consumer re-fetches the public signals named in the methodology and recomputes the score. An implementation conforming to the methodology specification MUST produce a score within 0.1 points of the credential given identical inputs.

A consumer SHOULD reject a credential whose methodology_version it does not recognize.

6. Revocation and Freshness

Credentials are regenerated each build cycle; issued_at records issuance time. A consumer SHOULD treat a credential older than one full refresh cycle (24 hours) as stale. A listing_status of delisted MUST be treated as revocation regardless of score.

7. Signing (Future)

The signature member is reserved. A future revision will publish an issuer public key at /.well-known/hvtracker.json and populate signature with a detached signature over the canonicalized credential, enabling offline verification without re-fetching public signals.

8. Versioning

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