# Agent-published content: format specification

**Version 0.1. Experimental — expect changes.**

Why this exists and what it does not claim: https://porkbun.com/agent-provenance

This defines how an AI agent publishes a file so that anyone can later check
**who published it** and **whether it has changed since**, and how to verify
such a claim.

It is deliberately implementable without Porkbun. Everything a verifier needs
is public: DNS, a transparency log, and the document itself. Porkbun operates a
registry and offers convenience endpoints, but nothing here requires either.

## The three parts

| Part | What it is | Where it lives |
|---|---|---|
| **Identity** | A versioned name tied to a domain, with a certificate and a public append-only log entry | ANS (`ans://v1.0.0.host`) |
| **Manifest** | A signed JSON document listing what the site publishes, each file by hash | `/.well-known/apm.json` |
| **Marker** | One line inside a published file pointing at its manifest | the file itself |

The manifest is the evidence. The marker is only a pointer. The identity is
what makes either mean anything.

## 1. The manifest

A JSON object served over HTTPS. Conventionally at `/.well-known/apm.json`,
though a marker or `Link` header may point anywhere on the same origin.

```json
{
  "apm": "0.1",
  "spec": "https://porkbun.com/llms/guides/agent-content-format",
  "status": "experimental",
  "domain": "example.com",
  "identity": {
    "ans": "ans://v1.0.0.example.com",
    "agentId": "ee212f48-170a-4a06-865c-80d68527d98d",
    "transparencyLog": "https://tl.ans.porkbun.com/v1/agents/ee212f48-..."
  },
  "collections": [
    {
      "name": "products",
      "href": "https://example.com/apm/products.json",
      "sha256": "fc582d3bc4465fdc94bc6c34a0ba22a32ab105a4608abf9ef0c885b4681798da",
      "bytes": 17819,
      "type": "schema.org/Product",
      "format": "json",
      "updated": "2026-11-16T19:40:00Z",
      "ttl": 86400
    }
  ],
  "generatedAt": "2026-11-17T22:20:20Z",
  "sig": { "alg": "ES256", "kid": "ans://v1.0.0.example.com", "jws": "eyJ…..MEQC…" }
}
```

`spec` names this document. A manifest found on its own is otherwise
unreadable to anyone who has not seen the format before: it is how a
consumer learns what `"apm": "0.1"` means. It sits inside the signature, so
it cannot be swapped for a pointer to a different format.

**Required:** `apm`, `domain`, `identity.ans`, `collections`, `sig`.
**Strongly recommended:** `spec`.
**Optional and carried verbatim:** `entity`, `policy`, `endpoints`, `notes`,
`status`, `generatedAt`, and on each collection `type`, `format`, `schema`,
`source`, `updated`, `id`, `description`, `ttl`, `bytes`.

Each `collections[]` entry MUST have `href` and `sha256` (lowercase hex,
SHA-256 of the exact bytes served at that URL).

`policy` is a statement by the publisher, not an enforcement mechanism —
typically `training`, `quote`, `attribution`. It is inside the signature, so it
is attributable; it is not self-enforcing.

## 2. The signature

`sig.jws` is a **detached** JWS in compact serialization (RFC 7515 Appendix F):
the payload segment is empty.

- `alg` MUST be `ES256`, read from the protected header only.
- `x5c[0]` MUST carry the signing certificate (base64 DER). **This is required,
  not optional:** the transparency log publishes certificate *fingerprints*,
  never public keys, so a third party's only source for the key is the
  signature itself.
- `kid` is the `ans://` name being claimed.
- The signed payload is the **RFC 8785 (JCS) canonical form of the manifest
  with `sig` removed**.

**Canonicalisation constraint.** Independent JCS implementations disagree on
ECMAScript number formatting. A conforming manifest therefore uses only values
that serialise unambiguously: objects, arrays, strings, booleans, null, and
**integer** numbers, with ASCII object keys. A verifier that encounters anything
else MUST refuse rather than guess.

## 3. The marker

One line inside a published file, wrapped in whatever comment syntax the format
uses:

```
agent-provenance: ans://v1.0.0.example.com manifest=https://example.com/.well-known/apm.json verify=https://porkbun.com/llms/guides/verify-agent-content
```

- `agent-provenance:` followed by the `ans://` name.
- `manifest=` the manifest URL. `verify=` a human- or machine-readable
  explanation. Both are hints; order is not significant.
- Formats with no comment syntax (JSON, images) carry no marker. JSON documents
  may carry the pointer as a field instead.

A marker MUST be written **before** the file is hashed for the manifest.

**The marker is not a claim.** Anyone can paste it onto anything. Its only
function is to tell a reader where the evidence is. A verifier MUST resolve it
and MUST NOT treat its presence as provenance. It is expected to survive onto
copies and excerpts; when it does, the hash comparison is what reveals that the
copy is not what was published.

## 4. Verifying

Normative order. Steps 1–3 establish *who*; step 4 establishes *what*.

1. **Find the manifest**: the marker's `manifest=`, else a
   `Link: <...>; rel="agent-manifest"` header, else a
   `<link rel="agent-manifest">` element, else `/.well-known/apm.json` on the
   same origin.
2. **Verify the signature**: take the certificate from `x5c[0]`, confirm its
   URI SAN equals the claimed `ans://` name, and verify the detached JWS over
   the JCS form of the manifest with `sig` removed.
3. **Anchor the certificate**: resolve `_ans-badge.<host>` in DNS, fetch the
   transparency log entry it names, and require `sha256` of the certificate's
   DER to appear among that entry's attested identity certificates.

   **This step is the whole scheme.** A certificate anyone minted, naming a real
   agent, with a genuine signature made by its own key, passes steps 1 and 2.
   Only the log distinguishes it from the real one.
4. **Check the file**: find the `collections[]` entry whose `href` is the file
   you hold, hash your bytes, compare. The signature covers the *manifest*;
   files are covered only by these hashes. **A verifier that stops at step 3 can
   be fed altered content under a valid signature.**

### Outcomes

A verifier SHOULD distinguish:

- **verified** — covered by a signed manifest and the bytes match
- **altered** — covered, bytes differ. Do not attribute the content.
- **unclaimed** — a manifest exists but does not list this file. No claim is
  made; this is not a failure.
- **none** — no manifest. True of almost the entire web; not a red flag.
- **inconclusive** — could not fetch enough to decide. Not a negative verdict.

Collapsing the last three into "failed" makes a verifier useless, because
`none` is the normal state of the world.

## 5. Authorship is not liveness

These are different questions and MUST be reported separately.

- **Authorship** is historical. A signature made by a certificate that has since
  **expired** is still valid evidence of who produced the document: the key
  outlives the certificate, and a registry that attests an agent's last
  certificate after expiry lets work outlive the agent. An agent that shut down
  years ago should still be credited.
- **Liveness** is current: is the agent active, is its registration valid.

An expired signing certificate is a warning, not a failure. A **revoked**
registration is more nuanced: revocation for key compromise should invalidate
past signatures retroactively, while cessation of operation or supersession
should not.

**More than one attested identity certificate is normal.** Re-issuing adds one
and the previous stays valid until it expires. Membership in the attested set
is necessary but not sufficient — check the presented certificate's own validity
window too.

## 6. Security considerations

- **A chain handed to you beside a certificate is not a trust anchor.** Fetch
  the issuing root independently, or pin it.
- **Do not sign HTML bytes.** CDNs, minifiers and injected scripts rewrite them,
  so a byte signature over a page fails for reasons unrelated to authenticity.
  Sign a claim *about* the bytes — which is what `collections[]` is.
- **Caches cause false mismatches.** A file republished moments ago may still be
  served stale. Re-check before reporting tampering.
- **Markers are forgeable; that is by design.** They are discovery, not
  evidence.
- **Provenance is not quality.** It says who published something and that it has
  not changed. It says nothing about whether the content is accurate, safe or
  appropriate. Never present it as an endorsement.

## 7. Checking one, start to finish

Everything below is public and checkable right now, with no account:

```
# the whole chain in one call
curl 'https://api.porkbun.com/api/json/v3/ans/verifyArtifact?url=https://example.com/data/products.json'

# or do it yourself, for any host that publishes one
curl https://example.com/.well-known/apm.json              # the manifest
dig +short TXT _ans-badge.example.com                      # where its log entry is
curl https://tl.ans.porkbun.com/v1/agents/<agentId>        # attested certificates
curl https://tl.ans.porkbun.com/ca/identity-root.pem       # the issuing root
```

Substitute a host that publishes a manifest. The two Porkbun URLs are the
only fixed ones, and only for agents registered with Porkbun: for an agent
registered elsewhere, the log comes from that host's own `_ans-badge` record.

The identity root for Porkbun-issued agent certificates pins to
`sha256(DER) = d914e2e37b5810362cb9575d54784ff3a95abe01ba3ec703d9bff826a280edcc`.

## 8. What is Porkbun-specific, and what is not

Not specific: the manifest format, the detached JWS, the marker, and the
verification algorithm. Any registry that issues identity certificates and
publishes them in an append-only log can be verified by the same steps, and
Porkbun's own verifier checks agents registered elsewhere.

Specific: the `tl.ans.porkbun.com` log and identity root used by agents
registered with Porkbun, and the convenience endpoints under
`api.porkbun.com/api/json/v3/ans/`. A verifier follows the log named by the
*agent's own DNS record*, not a hardcoded one.


---

## More

- Short overview (start here): https://porkbun.com/llms.txt
- Guides (how-tos): https://porkbun.com/llms/guides
- Help articles (knowledge base) as Markdown: https://porkbun.com/llms/kb
- Topic index: https://porkbun.com/llms
- Full reference (one file): https://porkbun.com/llms-full.txt
- OpenAPI spec (full schemas): https://porkbun.com/api/json/v3/spec
- Official MCP server: https://porkbun.com/mcp (`npx -y @porkbunllc/mcp-server`)
- Create API keys: https://porkbun.com/account/api
