Documentation

GoVidence receives records of AI agent actions, signs the recorded evidence and lets each account inspect its own traces, policy history and compliance reports.

Verification checks signed content for changes. Reports organize the available evidence against framework requirements; they do not establish that every requirement is satisfied.

GoVidence traces and prepares control. Policy decisions are recorded preview values, not actions enforced by GoVidence.

Recorded evidence

What the client submitted about an agent action. A record alone does not establish that the action happened or that all activity was captured.

Cryptographic integrity

Whether the verified content matches the signed content, using an authentic, trusted public key. This is separate from the truth of the original record.

Regulatory compliance

Whether the applicable legal requirements are met. This can require organizational, contractual and operational evidence that agent traces cannot establish.

The Compliance page offers govidence-verify.js, a single standalone file. It requires Node.js 18 or later and has no external package dependencies: it uses only Node’s built-in modules and includes its own JSON canonicalization. Run it from the directory containing the file:

node govidence-verify.js package.json keys.json
node govidence-verify.js package.json keys.json --expect-fingerprint sha256:<hex>

• package.json: a saved Verification Package, or an object containing a packages array. This is the evidence input, not a dependency manifest.
• keys.json: the key registry, supplied locally. Save a copy of /.well-known/govidence-keys.json yourself; the verifier does not download it.
• --expect-fingerprint sha256:<hex> (optional, the only option): the verifier recomputes the SHA-256 fingerprint of the trace signing key’s raw public key, requires it to equal the registry entry’s fingerprint, and then requires that registry fingerprint to equal the value you supplied. A mismatch returns unknown_key. Obtain the expected value through a separate channel.

Verification reads only those two local files, makes no network calls and requires no secret or private key.

The package format is govidence.verification-package.v1, with trace domain govidence.trace.ed25519.v1. The verifier supports trace signature formats 2 and 3 with Ed25519 payload version 1.

The envelope contains package_format, domain, trace_id, signed_payload, signature, key_registry_url, policy_event_id, policy_event_reference and, when a linked event is available, policy_event. The signature contains alg, key_id, public_key_fingerprint, value.

The signed trace payload contains signature_format, key_version, id, account_id, timestamp, agent_id, action_type, input, output, status, tokens, cost, policy_applied, policy_id, decision, context, candidate_ref, candidate_ref_key_version, ed25519_payload_version, ed25519_key_id, public_key_fingerprint. Format 3 also binds policy_hash. These files can contain account identifiers and client-submitted content.

A linked policy event contains its domain, event_id, signed_payload and signature. Its payload contains event_id, policy_id, account_email, event_type, occurred_at, before_snapshot, after_snapshot, payload_version, ed25519_key_id, public_key_fingerprint, plus actor_id for payload version 2.

The verifier checks the event’s Ed25519 signature under govidence.policy_event.ed25519.v1. It then computes SHA-256 over govidence.policy_state.v1, a newline and the JCS-canonicalized normalized policy snapshot from after_snapshot, and compares the result with the trace’s signed policy_hash.

The snapshot uses id, name, description, action, decision, agents, active, created_at, NFC-normalized strings and the verifier’s legacy decision normalization. Missing description becomes an empty string; missing agents becomes an empty array. The unsigned policy_event_id is only a pointer, not the trust link. A matching policy hash is meaningful only when the trace signature is valid. With no embedded event, no policy-link result is returned.

While signed in, GET /api/verification-package?id=<trace_id> returns one account-scoped package. Without id, the response contains a packages array for the account’s traces with Ed25519 signatures. Packages use stored values without re-signing.

The public registry at /.well-known/govidence-keys.json contains registry_format, domain, keys. Its format is govidence.key-registry.v1.

Each key entry contains key_id, alg, public_key, public_key_fingerprint, status, valid_from, retired_at, compromised_at. The public key is the raw 32-byte Ed25519 key encoded as base64url without padding. Its fingerprint is sha256: followed by the lowercase hexadecimal SHA-256 digest of those raw bytes.

Active and retired keys can verify signatures; the command-line output notes a retired trace key. A compromised key returns key_compromised, not valid. Retired and compromised keys stay in the registry so older records remain checkable. The verifier explicitly rejects compromised keys; it does not otherwise validate the status value or use the key dates as validity cutoffs.

Compare the fingerprint through a separate channel before trusting your saved registry. The registry is served by GoVidence itself; this page does not establish an independent trust anchor. The expected-fingerprint option checks the trace signing key, not the linked policy event’s key.

Checks stop at the first applicable result. Trace and embedded policy-event results are reported separately:

valid

The trace passes format, signature presence, key binding, registry and Ed25519 checks. For an event, its signature must also verify and its recomputed policy hash must equal the trace’s signed policy_hash.

invalid

Trace key IDs or payload/envelope fingerprints disagree, signature length is not 64 bytes, or cryptographic verification fails or throws. Events also return invalid for the wrong domain or mismatched event IDs. This is a failed check, not proof of who changed a record or why.

unknown_key

The key is absent or not Ed25519, its decoded public key is not 32 bytes, or its computed fingerprint differs from the registry. For a trace, a mismatch with the supplied expected fingerprint also returns this result. Verification is unavailable; alteration is not established.

key_compromised

After key-binding checks, the registry marks the signing key compromised. It is not trusted.

missing_signature

The signature object, signed payload or signature value is absent. This does not establish alteration.

unknown_format

The trace package is absent, its package format or domain is unsupported, its Ed25519 payload version is not 1, or its signature format is neither 2 nor 3. For an embedded event, the payload version is neither 1 nor 2.

hash_mismatch

Only for a policy event: its signature verifies, but the trace has no string policy_hash or the recomputed after_snapshot hash differs from it.

With no embedded policy event, the link check returns null and the command prints no event result. If the trace is not valid, the command warns that its policy_hash is not trusted, even if the event check reports valid.

The command exits with 0 when all trace checks are valid and any event result is valid or missing_signature; 1 when a trace check fails or an event returns another result; 2 when either required file argument is missing. Unreadable files or invalid JSON throw rather than returning a verification status.

A valid signature checks that the content matches the bytes signed by the private key corresponding to the supplied public key. It does not prove:

• that the agent actually performed the action;
• that the data is true or complete;
• that no trace was omitted;
• that the recorded time was attested by a third party;
• that a legal or regulatory obligation is met;
• that the private key was never compromised.