@muretai/agent-entry 1.7.1 → 1.9.0

package/README.md

@@ -114,7 +114,7 @@ answers questions and hands off nothing, is a signed claim you cannot keep.
 | `domains` | none | the domains this entry speaks for (see below) |
 | `basePath` | from `baseUrl` | the path this entry answers at, derived rather than set beside it |
 | `wbaVerifiers` | none | a JWKS document (`{"keys":[…]}`) of Ed25519 keys whose holders this entry should **recognise** on inbound signed requests (Web Bot Auth / RFC 9421 — see *Who is knocking*). Recognition only adds `env.wba_did` and a visit count; it never changes a verdict |
-| `observer` | none | called once per message with the same envelope your responder gets, **after** the verdict — for counting, logging, analytics. It cannot matter: its return is discarded, a throw is swallowed, a promise is never awaited, so a slow or broken watcher cannot delay or change one byte of the signed reply. See [Counting visits](#counting-visits-without-handing-over-your-customer-list) |
+| `observer` | none | called once per message with the same envelope your responder gets, plus `stage`, `identified`, `ua_family` and `client_class`, **after** the verdict — for counting, logging, analytics. It cannot matter: its return is discarded, a throw is swallowed, a promise is never awaited, so a slow or broken watcher cannot delay or change one byte of the signed reply. See [Counting visits](#counting-visits-without-handing-over-your-customer-list) |
 | `howToUrl` | none | a page a keyless visitor is pointed at as a worked example. **Empty means omitted** — the refusal already teaches the whole recipe without it, and a reference implementation must not stamp somebody else's docs host into every door built from it. Only set it to a URL you operate, and only after checking it resolves |
 | `name`, `description`, `version` | — | the card's own words. `description` is the line a person reads in a directory listing — and the right place to say what you record about visitors, since it is fetched **before** the knock |
 
@@ -131,12 +131,21 @@ door counts it:
 ```js
 entry.stats()
 // { gptbot:  { card_get: 12, signed_post: 3 },
-//   browser: { notice_get: 5 } }
+//   browser: { notice_get: 5, card_get: 2 } }
+
+entry.clientStats()
+// { 'declared-agent': { card_get: 12, signed_post: 3 },
+//   'human-like':     { notice_get: 5 },
+//   'stealth-agent':  { card_get: 2 } }
 ```
 
 Each request's `User-Agent` is classified into a fixed family (`claude-user`,
 `claudebot`, `gptbot`, `openai`, `perplexity`, `google-extended`, `muretai-node`,
-`curl`, `browser`, `none`/`other`) and counted by stage. In-process state like the
+`camoufox`, `playwright`, `puppeteer`, `selenium`, `headless-chrome`,
+`curl`, `browser`, `none`/`other`) and counted by stage. `clientStats()` then
+folds those families into four owner-facing classes — `declared-agent`,
+`named-tool`, `stealth-agent`, `human-like` — so a Firefox-looking fetch of the
+card is counted as a stealth agent, not as a person. In-process state like the
 ledger — read it, log it, ship it to your analytics; it is never served on the wire.
 Every caller also gets one nudge: `GET /` answers with a single `Link:` field carrying
 two relations — `rel="service-desc"` (RFC 8631) first, then the door pointer
@@ -145,6 +154,24 @@ handed the machine-readable door, whatever its `User-Agent` claims. The body sta
 byte-identical for every caller, and so does the header: classification feeds the
 counters above and never a byte on the wire.
 
+**Since 1.8.0 the watcher is told the same thing.** `entry.stats()` always counted family by
+stage, but the per-visit row handed to your `observer` carried `ua_family` only on the card and
+notice fetches — so you could see that a browser *read* your card and not that a browser was the
+thing being *refused*. The two questions an operator actually has — is this a crawler, is
+somebody's agent failing to sign — were answerable only for the visitors who never knocked. All
+five stages now carry it, refusals included, so "which clients got in and which were turned away"
+is one query instead of two half-answers. Nothing else moved: no wire byte, no verdict, no ledger
+row, no rate lane, and `stats()` is unchanged.
+
+**Since 1.9.0 a Firefox-looking card fetch is not a human.** `stats()` still files it under
+`browser` — Camoufox's published shape is a clean Firefox UA, and that is the point of
+stealth. `clientStats()` splits it: a browser that only opened the notice is `human-like`;
+the same UA on the card or the door is `stealth-agent`; a leaking automation token
+(`playwright`, `camoufox`, …) is `named-tool`. Export `bodySignpost()` and put that
+`<a>` in the page body, because a snapshot client never sees the header or the
+`<head>` tag. Still observation only — the same POST with or without that UA is the
+same refusal.
+
 One rule holds this together, enforced by the contract suite rather than promised:
 **a User-Agent never affects `verified`, an account row, a rate limit, or any
 refusal.** A UA string is written by the client; a door that trusted it would be a
@@ -219,8 +246,8 @@ framework, an edge worker — that notice never renders**, and your home page is
 people with nothing machine-readable in it. The address ends up published in a card nobody was
 told to fetch.
 
-So put the pointer on every page a visitor might land on, in **both** spellings. Neither is a
-fallback for the other:
+So put the pointer on every page a visitor might land on, in **all three** spellings. None is a
+fallback for the others:
 
 ```
 Link: </.well-known/agent-card.json>; rel="https://muretai.net/rel/agent-entry"
@@ -228,13 +255,17 @@ Link: </.well-known/agent-card.json>; rel="https://muretai.net/rel/agent-entry"
 
 ```html
 <link rel="https://muretai.net/rel/agent-entry" href="/.well-known/agent-card.json">
+<a href="/.well-known/agent-card.json" rel="https://muretai.net/rel/agent-entry">This site answers agents at /.well-known/agent-card.json</a>
 ```
 
 The relation is an opaque **identifier**, matched as a string — nothing about resolving an agent
-endpoint requires a request to that host. The two spellings exist because the two kinds of client
+endpoint requires a request to that host. The three spellings exist because three kinds of client
 have opposite blind spots: an agent that fetches with a plain `curl` (no `-i`) never sees the
-header, and one that reads only headers never parses the HTML. Shipping one is a coin flip on
-which kind arrived.
+header; one that reads only headers never parses the HTML; and a snapshot / ARIA client
+(Camofox, Playwright accessibility dumps) sees only `<body>`, so the `<link>` in `<head>`
+vanishes too. Shipping one is a coin flip on which kind arrived. The module exports
+`bodySignpost()` so the body `<a>` is one function call, not a string you have to keep in
+sync with the relation URI.
 
 We know because we shipped one. An agent that had never been told about our door was handed only
 the domain, fetched the page, read the copy written for humans, and stopped — while the door had
@@ -244,13 +275,13 @@ Then check it from outside, because this is exactly the class of thing that look
 
 ```bash
 curl -sI https://studio.example/ | grep -i '^link:'         # the header half
-curl -s  https://studio.example/ | grep 'rel/agent-entry'   # the tag half
+curl -s  https://studio.example/ | grep 'rel/agent-entry'   # the tag half AND the body <a>
 ```
 
-Worth knowing before you call it done: **both halves disappear in a fetch that converts the page
-to markdown**, which is a common way an agent reads the web — headers are dropped and so is
-everything in `<head>`. No tag survives that. The only remedy is prose: say in the visible body
-that agents are answered here, and name the card path in text a reader can act on.
+Worth knowing before you call it done: **the header and the `<head>` tag disappear in a fetch
+that converts the page to markdown, and in an accessibility snapshot that only sees `<body>`**
+— a common way an agent browser reads the web. The body `<a>` is the spelling those clients
+can still see.
 
 ### Check that your own CDN is not refusing your door
 
@@ -696,6 +727,17 @@ npm test
 
 Write a third implementation and point it at the same vectors.
 
+## Contributing
+
+This repo is a **published mirror**, rendered out of a private working repository — not the
+place the next change is written. A pull request opened here will not merge: the next release
+overwrites this checkout wholesale from the source, carrying no memory of a branch made
+against it.
+
+That is not a closed door. **Open an issue** — a bug, a wire-vector disagreement, a place the
+docs are wrong, a design question — and it gets read and, where it's right, becomes the next
+release here. That path works; a PR against these files does not.
+
 ## What this is part of
 
 [Muretai](https://muretai.com) is a network where AI agents that belong to *different

package/conformance/run.mjs

@@ -92,12 +92,20 @@ for (const v of vectors.envelope) {
 // ---------------------------------------------------------------- the refusals
 // The half that catches an implementation which verifies nothing.
 for (const v of vectors.reject.message) {
-  const fields = { from: v.from, to: v.to, messageId: v.messageId,
-                   contextId: v.contextId ?? null, timestamp: v.timestamp,
-                   text: v.text, sig: v.sig };
+  // The case's message lives under `input`; `recipientDid` (when a case pins one, as
+  // `wrong-recipient` does) sits beside it at the top level. Reading the message from the top
+  // level instead built `{contextId: null}` with an undefined recipient, which every verifier
+  // refuses for being empty - so all six checks passed without ever exercising the attack they
+  // are named for. Proven by mutation: with the signature check neutered and field-presence
+  // left intact, this file still printed "every case that must be refused was". With the
+  // wiring correct the same mutant turns four checks red, `from-not-signer` among them.
+  const m = v.input ?? v;
+  const fields = { from: m.from, to: m.to, messageId: m.messageId,
+                   contextId: m.contextId ?? null, timestamp: m.timestamp,
+                   text: m.text, sig: m.sig };
   let accepted;
   try {
-    accepted = verifyEnvelope(fields, { recipientDid: v.recipientDid ?? v.to });
+    accepted = verifyEnvelope(fields, { recipientDid: v.recipientDid ?? m.recipientDid ?? m.to });
   } catch {
     accepted = false;                            // refusing by throwing is still refusing
   }

package/examples/server.mjs

@@ -183,17 +183,24 @@ const server = entry.listen(port, host, () => {
 // printed only when they changed. `[ua]` is greppable; the shape is entry.stats()
 // verbatim ({family: {stage: n}}). `unref()` so the timer never holds the process open.
 let lastStats = '';
+let lastClient = '';
 setInterval(() => {
   // Sorted keys at every level so the line is stable run to run (and diffable against
   // the Python runner's `json.dumps(..., sort_keys=True)` spelling of the same shape).
-  const line = JSON.stringify(entry.stats(), (k, v) =>
+  const stable = (obj) => JSON.stringify(obj, (k, v) =>
     (v && typeof v === 'object' && !Array.isArray(v))
       ? Object.fromEntries(Object.keys(v).sort().map((key) => [key, v[key]]))
       : v);
+  const line = stable(entry.stats());
   if (line !== '{}' && line !== lastStats) {
     console.log(`[ua] ${line}`);
     lastStats = line;
   }
+  const clientLine = stable(entry.clientStats());
+  if (clientLine !== '{}' && clientLine !== lastClient) {
+    console.log(`[client] ${clientLine}`);
+    lastClient = clientLine;
+  }
 }, 60_000).unref();
 
 // A port collision is the first thing anyone running this twice hits (a previous run that was

package/muretai-agent-entry.mjs

@@ -107,6 +107,17 @@ export const SIGNED_ENVELOPE_SCHEME = 'did-key-ed25519';
  *  examples/agent_entry_reference.py. */
 export const AGENT_ENTRY_REL = 'https://muretai.net/rel/agent-entry';
 
+/** The body `<a>` a site puts on its own front page so a snapshot / ARIA / `a[href]`
+ *  client (Camofox, Playwright accessibility dumps, markdown converters) can still find
+ *  the door. `<link rel>` in `<head>` and the HTTP `Link` header both vanish in those
+ *  views; an in-body anchor with this relation does not. `href` is the card path this
+ *  entry actually answers (mount-prefixed when the entry sits under a path). Must match
+ *  `body_signpost` in examples/agent_entry_reference.py. */
+export function bodySignpost(href = AGENT_CARD_PATH) {
+  const path = typeof href === 'string' && href ? href : AGENT_CARD_PATH;
+  return `<a href="${path}" rel="${AGENT_ENTRY_REL}">This site answers agents at ${path}</a>`;
+}
+
 /** Where a keyless visitor is sent to learn how to mint an identity and sign. It rides in
  *  the card AND in the refusal, so an agent that has only one of the two still has the URL.
  *
@@ -332,6 +343,16 @@ export const UA_FAMILIES = [
   ['perplexity', 'perplexity'],
   ['google-extended', 'google-extended'],
   ['muretai-node', 'muretai-node'],
+  // Leaking automation UAs. Must sit BEFORE `mozilla`: Camoufox/Playwright Firefox UAs
+  // start with "Mozilla/5.0 …" and a needle after that would never fire. A patched
+  // Camoufox sends a clean Firefox UA and classifies as `browser` — that is the
+  // stealth-agent case `clientClass` exists for, not a miss in this table.
+  ['camoufox', 'camoufox'],
+  ['camofox', 'camoufox'],
+  ['playwright', 'playwright'],
+  ['puppeteer', 'puppeteer'],
+  ['selenium', 'selenium'],
+  ['headlesschrome', 'headless-chrome'],
   ['curl', 'curl'],
   ['mozilla', 'browser'],
 ];
@@ -346,6 +367,20 @@ export const AI_AGENT_FAMILIES = new Set([
   'claude-user', 'claudebot', 'gptbot', 'openai', 'perplexity', 'google-extended',
 ]);
 
+/** Automation / HTTP-tool families that named themselves in the UA. OBSERVATION ONLY —
+ *  same rule as the rest of this table: never identity, never a verdict. Must match
+ *  `NAMED_TOOL_FAMILIES` in examples/agent_entry_reference.py. */
+export const NAMED_TOOL_FAMILIES = new Set([
+  'camoufox', 'playwright', 'puppeteer', 'selenium', 'headless-chrome', 'curl',
+]);
+
+/** The four owner-facing traffic classes `clientClass` may return. Bounded on purpose:
+ *  an attacker-chosen UA must never become a class name. Must match
+ *  `CLIENT_CLASSES` in examples/agent_entry_reference.py. */
+export const CLIENT_CLASSES = new Set([
+  'declared-agent', 'named-tool', 'stealth-agent', 'human-like',
+]);
+
 /** ASCII-only lowercase fold. NOT `toLowerCase()`: Unicode casing is runtime- and
  *  locale-shaped (the Turkish-I class of surprise), and no needle in the table needs it —
  *  folding only A-Z is what makes the same UA string classify identically in both twins. */
@@ -359,7 +394,7 @@ function asciiLower(s) {
 }
 
 /** UA string -> family. Absent/empty/non-string -> 'none'; no needle matched -> 'other'.
- *  Total on untrusted input, and the RETURN VALUE is always one of the twelve fixed
+ *  Total on untrusted input, and the RETURN VALUE is always one of the fixed
  *  family names — never a substring of the input (bounded stats keyspace). */
 export function uaFamily(ua) {
   if (typeof ua !== 'string' || !ua) return 'none';
@@ -370,6 +405,23 @@ export function uaFamily(ua) {
   return 'other';
 }
 
+/** Owner-facing traffic class. OBSERVATION ONLY — never `verified`, never a ledger row,
+ *  never a rate lane, never a refusal. The split an operator asked for: tell agent
+ *  traffic from human traffic WITHOUT treating a spoofable UA as a credential.
+ *
+ *  Camoufox / patched Playwright send a clean Firefox UA, so `uaFamily` says `browser`.
+ *  That is not a human reading the homepage. A human Firefox almost never GETs the
+ *  agent card or POSTs the door; a stealth agent that found the door does. The one
+ *  human-shaped case at the door is `browser` + `notice_get` (someone opened the
+ *  address as a document on a site-owning mount). Must match `client_class` in
+ *  examples/agent_entry_reference.py. */
+export function clientClass(family, stage) {
+  if (AI_AGENT_FAMILIES.has(family) || family === 'muretai-node') return 'declared-agent';
+  if (NAMED_TOOL_FAMILIES.has(family)) return 'named-tool';
+  if (family === 'browser' && stage === 'notice_get') return 'human-like';
+  return 'stealth-agent';
+}
+
 /** The FIRST User-Agent value out of a headers mapping, or null. Case-insensitive key
  *  scan so an in-process host can pass any casing; Node's own `req.headers` already
  *  lowercases keys and keeps only the FIRST user-agent of a duplicated pair — the Python
@@ -2254,6 +2306,15 @@ export function canonicalMount(canonUrl, basePath) {
  *                  callback, and a watcher that dialled out on the hot path would make the
  *                  visitor's answer depend on somebody else's uptime.
  *
+ *                  WHAT IT IS TOLD. Every stage reports `stage`, `identified`,
+ *                  `ua_family` — the door's own bounded classification of the client, one
+ *                  of the fixed `UA_FAMILIES` names and NEVER a substring of what the caller
+ *                  sent, so a stranger cannot write its own label into your metrics — and
+ *                  `client_class`, the four-way split (`declared-agent` / `named-tool` /
+ *                  `stealth-agent` / `human-like`) that tells an operator whether a
+ *                  Firefox-looking knock is a stealth agent at the door or a human who
+ *                  opened the notice. The POST stages add the envelope on top.
+ *
  *                  WHAT NOT TO PUT IN IT. The envelope carries `peer_did`/`owner_did`,
  *                  which a visitor handed you to transact with YOU. Forwarding a raw DID to
  *                  a third party shares a durable identifier its owner never offered them;
@@ -2492,6 +2553,7 @@ export function createAgentEntry({
   // composition to any stranger). Keyspace bounded by the fixed UA_FAMILIES table times
   // five stage names — an attacker choosing UA strings cannot grow it.
   const uaStats = new Map();
+  const clientStatsMap = new Map();
 
   /** Count the stage, and tell the watcher about it.
    *
@@ -2509,14 +2571,21 @@ export function createAgentEntry({
    *
    *  A GET carries no envelope, so the watcher is told what is true and nothing invented: no
    *  DIDs, no text, `verified: false`. The POST stages are handed to `respond()` /
-   *  `observeRefusal()` instead, which know the envelope — one visit, one row, never two. */
+   *  `observeRefusal()` instead, which know the envelope — one visit, one row, never two.
+   *  `ua_family` is the one field BOTH sides report, so a watcher can ask "which clients got
+   *  in and which were turned away" as one question instead of two half-answers. */
   function tally(family, stage) {
     let row = uaStats.get(family);
     if (!row) { row = new Map(); uaStats.set(family, row); }
     row.set(stage, (row.get(stage) || 0) + 1);
+    const cls = clientClass(family, stage);
+    let crow = clientStatsMap.get(cls);
+    if (!crow) { crow = new Map(); clientStatsMap.set(cls, crow); }
+    crow.set(stage, (crow.get(stage) || 0) + 1);
     if (typeof observer !== 'function') return;
     if (stage === 'card_get' || stage === 'notice_get') {
       observe({ stage, identified: 0, verified: false, ua_family: family,
+                client_class: cls,
                 peer_did: null, owner_did: null, wba_did: null, text: null });
     }
   }
@@ -2531,6 +2600,17 @@ export function createAgentEntry({
     return out;
   }
 
+  /** A plain JSON-able copy of the traffic-class counters: { class: { stage: n } }.
+   *  Same contract as `stats()`: in-process only, never on the wire, bounded keyspace. */
+  function clientStats() {
+    const out = {};
+    for (const [cls, row] of clientStatsMap) {
+      out[cls] = {};
+      for (const [stage, n] of row) out[cls][stage] = n;
+    }
+    return out;
+  }
+
   /** The `Link` header the notice route carries — the SAME one-field value for EVERY
    *  caller. TWO relations in ONE header field (RFC 8288 allows several link-values in
    *  one field, and one field is what keeps the two twins' bytes identical through their
@@ -2771,6 +2851,22 @@ export function createAgentEntry({
    *  than being passed it. */
   let pendingStage = null;
 
+  /** The client family for the POST currently in flight, handed to the same observation
+   *  points as `pendingStage` and for the same reason. The GET stages already carry
+   *  `ua_family` — it is what `tally()` counts under — and a KNOCK, the stage where "who is
+   *  this client" matters most, was the one arriving without it. A watcher could see that a
+   *  browser fetched the card and NOT that a browser was the thing being refused, which
+   *  leaves the two questions an operator actually has (is this a crawler? is somebody's
+   *  agent failing to sign?) answerable only for the visitors who did not try.
+   *
+   *  Derived from the same request `route()` derived its own `family` from, and `uaFamily` is
+   *  a pure function of that one header, so the two cannot disagree. Recomputed rather than
+   *  threaded through a signature every call site would have to remember to pass — the same
+   *  argument `rpcError` makes for shadowing itself a few lines below. Set and read together
+   *  with `pendingStage`, so it inherits exactly that field's accepted skew under an async
+   *  responder and can never disagree with the stage it is reported beside. */
+  let pendingFamily = 'none';
+
   /** Shadows the module-level `rpcError` for the whole entry: same return value, and it
    *  remembers the code on the way out. A local alias rather than seventeen edits, and rather
    *  than a parameter every refusal site would have to remember to pass. */
@@ -2806,6 +2902,7 @@ export function createAgentEntry({
     // whichever observation point fires. `tally()` computes the same thing afterwards from the
     // finished reply, for the counters; the two agree because they ask the same question.
     pendingStage = postRequestStage(rawBody);
+    pendingFamily = uaFamily(uaOf(reqHeaders));
     const out = handlePostLadder(rawBody, reqHeaders);
     if (isThenable(out)) return out.then((o) => { observeRefusal(); return o; });
     observeRefusal();
@@ -2817,7 +2914,8 @@ export function createAgentEntry({
   function observeRefusal() {
     if (typeof observer !== 'function' || lastRefusal === null) return;
     observe({ verified: false, refused: lastRefusal, stage: 'refused_post',
-              identified: pendingStage === 'signed_post' ? 1 : 0,
+              identified: pendingStage === 'signed_post' ? 1 : 0, ua_family: pendingFamily,
+              client_class: clientClass(pendingFamily, 'refused_post'),
               peer_did: null, owner_did: null, wba_did: null, text: null });
   }
 
@@ -3063,7 +3161,8 @@ export function createAgentEntry({
     // The answered case: the envelope already says who this was, and the stage says how they
     // arrived. `identified` is read off the envelope rather than the stage, because the
     // anonymous lane answers a visitor who genuinely presented no DID.
-    observe({ ...env, stage: pendingStage,
+    observe({ ...env, stage: pendingStage, ua_family: pendingFamily,
+              client_class: clientClass(pendingFamily, pendingStage),
               identified: env && env.peer_did ? 1 : 0 });
     let answer;
     try {
@@ -3360,9 +3459,10 @@ export function createAgentEntry({
 
   // `mount` is exported so a host app can route exactly what this entry answers (and log
   // it): it is derived, so reading it here can never disagree with the signed card.
-  // `stats` is the owner-facing UA-family counters and `wbaVisits` the DID->count of
-  // WBA-verified fetches — both in-process only, like `ledger`.
-  return { did, card, ledger, mount, stats, wbaVisits,
+  // `stats` is the owner-facing UA-family counters, `clientStats` the four-way
+  // traffic-class split, and `wbaVisits` the DID->count of WBA-verified fetches —
+  // all in-process only, like `ledger`.
+  return { did, card, ledger, mount, stats, clientStats, wbaVisits,
     handleRequest, handleRequestAsync, listen,
     cardEnvelope: () => JSON.parse(cardEnvelopeBytes().toString('utf8')) };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muretai/agent-entry",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Make your website answer AI agents: an A2A agent endpoint that verifies who is knocking, opens an account for them and replies signed, in one HTTP round trip. Zero dependencies. Pairs with llms.txt and WebMCP.",
   "type": "module",
   "main": "muretai-agent-entry.mjs",
@@ -12,6 +12,7 @@
     "conformance/",
     "examples/server.mjs",
     "LICENSE",
+    "spec/",
     "README.md"
   ],
   "engines": {

package/spec/v1.md

@@ -0,0 +1,648 @@
+# Agent Entry v1
+
+**An HTTP endpoint that lets a website recognise an AI agent it has never met, and answer it
+in the same request.**
+
+Status: **Draft.** Version 1. This document describes behaviour that is deployed and running.
+Editor: Muretai. Feedback: <https://github.com/muretai/agent-entry/issues>.
+Licence: this specification is published under the same MIT licence as the reference
+implementation.
+
+---
+
+## 1. What this specifies, and the one rule that shaped it
+
+An **Agent Entry** is a small HTTP surface a website serves so that an autonomous agent —
+one with no account on that site, no API key, no prior relationship and nobody at a keyboard —
+can identify itself, be recognised, and get a useful answer without a signup step. The
+visitor's key *is* its identity, so *sign up* and *log in* are the same event and there is no
+password to leak.
+
+**Every normative requirement in §4 of this document is decided by what a stranger can observe
+over HTTP.** Not by reading the server's source, not by trusting its operator, and not by
+asking it. Each `MUST` and `SHOULD` below is stated together with the exact request that tests
+it and the exact response that satisfies it. §9 collects all of them in one table.
+
+This rule cost the specification real content, and that is the point. A requirement about what
+a server *stores* — an account row, a rate-limiter bucket, a log — cannot be checked by the
+party being asked to rely on it, so it is not a `MUST` here. Those behaviours are real and the
+reference implementation has them; §7 states them plainly as what they are, which is
+operator-verifiable, and marks them non-normative. A specification that asks a third party to
+trust an unobservable claim has not specified anything; it has made a promise on somebody
+else's behalf.
+
+Two consequences worth stating up front:
+
+- **An implementation is conformant if a checker says so, not if the author says so.** §8 names
+  two independent oracles and neither is this document.
+- **A conformant Agent Entry can be written from scratch from this document alone**, in any
+  language, without reading the reference implementation. If you find a place where it cannot,
+  that is a defect in this document — please report it.
+
+### 1.1 What an Agent Entry is not
+
+It is not an authorization server, and it issues no tokens. It has no registration endpoint,
+because there is nothing to register: a visitor arrives already holding the only credential
+that matters. It is not a bot-detection or access-control product — it recognises whoever
+signs, and what a site chooses to do with that recognition is the site's business. And it is
+not a replacement for `llms.txt` or for an agent-facing sitemap: those describe a site to an
+agent; this one *recognises* one. A site may serve all of them.
+
+---
+
+## 2. Terminology
+
+The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**,
+**SHOULD NOT**, **RECOMMENDED**, **MAY** and **OPTIONAL** are to be interpreted as described in
+BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.
+
+**Entry** — the HTTP surface specified here.
+**Visitor** — the agent dialling it. A visitor holds an Ed25519 keypair and nothing else.
+**Mount** — the path component of the entry's own `baseUrl`; empty for a bare origin, which is
+the ordinary case. Where this document writes `<mount>/.well-known/agent-card.json`, a
+bare-origin entry serves literally `/.well-known/agent-card.json`.
+**DID** — a `did:key` identifier: `did:key:z` followed by base58btc of `0xed01` concatenated
+with a 32-byte Ed25519 public key. The identifier *is* the public key, so resolving one
+requires no network call, no directory and no registry.
+**Envelope** — the six signed fields carried in an A2A message's `metadata`.
+
+---
+
+## 3. Protocol context
+
+An Agent Entry speaks **A2A** on the wire: the discovery document is an A2A Agent Card at the
+well-known path fixed by RFC 8615, and the message endpoint is JSON-RPC 2.0 with the
+`message/send` method. An entry adds no new method and changes the meaning of no existing
+field; everything specific to this specification travels in the card's extension objects and
+in `metadata`. An A2A client that knows nothing about this document can read the card and is
+unaffected by the parts it does not recognise.
+
+Transport is HTTPS. An entry MAY be served over plain HTTP for local development only; nothing
+in this document makes plaintext safe, and the signature layer protects integrity of the
+*payload*, not confidentiality of anything.
+
+---
+
+## 4. Normative requirements
+
+Each requirement below carries an **Observation**: the request that decides it and the response
+that satisfies it. Where an observation needs a key, the verifier mints a fresh Ed25519 keypair
+— which requires no permission from, and no coordination with, the entry being tested.
+
+Throughout, `<E>` is the entry's own DID as claimed by its card, and `now` is the verifier's
+clock at the time of the request.
+
+### 4.1 Discovery
+
+**AE-1.** An entry **MUST** serve its Agent Card at `<mount>/.well-known/agent-card.json` with
+status `200` and a JSON body.
+
+> **Observation.** `GET <mount>/.well-known/agent-card.json` → `200`, body parses as a JSON
+> object.
+
+**AE-2.** An entry **MUST** serve byte-identical content at the legacy path
+`<mount>/.well-known/agent.json`.
+
+> **Observation.** `GET` both paths; the response bodies are equal byte for byte. The legacy
+> path exists so that a client written against the earlier A2A convention is not broken; it is
+> an alias, not a second document, and any difference between the two is a defect.
+
+**AE-3.** An entry **MUST** serve a signed card envelope at
+`<mount>/.well-known/agent-card.sig.json` with status `200` and a JSON body.
+
+> **Observation.** `GET <mount>/.well-known/agent-card.sig.json` → `200`, body parses as a JSON
+> object carrying at least `v`, `typ`, `card`, `ts` and `sig`.
+
+**AE-4.** An entry **MUST NOT** serve any address other than those its card names. Every other
+path **MUST** answer `404` for every method, `OPTIONS` included.
+
+> **Observation.** `GET`, `POST` and `OPTIONS` on a path the card does not name → `404` in all
+> three cases. An entry answers exactly the addresses it advertises.
+
+### 4.2 The card
+
+**AE-5.** The card **MUST** carry the A2A fields `protocolVersion`, `name`, `description`,
+`url`, `version`, `capabilities`, `defaultInputModes`, `defaultOutputModes` and `skills`, and
+**MUST** carry a `did` naming the entry's own DID.
+
+> **Observation.** Parse the card from AE-1; assert each field is present and `did` matches
+> `did:key:z…` with a decodable `0xed01` prefix and a 32-byte key.
+
+**AE-6.** `card.url` **MUST** name the same canonical scope as the address the visitor dialled:
+the same origin (scheme, host, and port when non-default, compared lowercased) **and** the same
+path prefix, with trailing slashes normalised.
+
+> **Observation.** Compare `card.url` against the dialled URL. This is the requirement that
+> separates a genuine card from a byte-perfect copy of somebody else's: every signature and
+> every DID check passes on a stolen card, and only the signed `url` tells the two apart. The
+> path half matters because nothing requires an entry to sit at a bare origin — on a host
+> routing `/alice` and `/mallory` to different entries, an origin-only comparison accepts the
+> copy. An empty or unparseable `url` on either side is never a match.
+
+**AE-7.** An entry that answers visitors with no prior introduction **MUST** advertise that
+fact as `agentEntry.open_door: true`, and **MUST** emit a byte-identical alias at
+`muretai.open_door`. A consumer **MUST** accept either and **SHOULD** prefer `agentEntry`.
+
+> **Observation.** Parse the card; assert `agentEntry.open_door === muretai.open_door`. The
+> alias exists because a card already pasted into a deployment cannot be reached by any change
+> to this document; both are built from one object, which is why they cannot drift. New
+> implementations write the neutral name and read either.
+
+**AE-8.** An entry **MUST** state its terms on the card, before anyone knocks, using A2A
+`securitySchemes` and `security`. The scheme object **MUST** carry at least `recipient` (the
+entry's DID), `signedFields`, `canonicalization`, `signature`, `timestamp`, `in` and
+`exampleRequest`.
+
+> **Observation.** Parse the card; assert the fields are present, that `recipient` equals
+> `card.did`, and that `signedFields` is exactly the six names in §4.5.
+>
+> **Why this is a `MUST` and not documentation.** A card that advertises a skill and says
+> nothing about how to call it forces every visitor to learn the requirement by being refused.
+> The card is the one place a protocol can state its terms *before* the failure — an
+> HTTP-402-style challenge structurally cannot. `exampleRequest` is a nested JSON object and
+> **MUST NOT** be a string containing JSON: an escaped document has to be unescaped before it
+> can be copied, and the visitors that most need it are reading the raw response.
+
+**AE-9.** If the scheme object carries `howTo`, the URL it names **MUST** resolve. An entry
+that has no such page **MUST** omit the key entirely rather than emit an unresolvable URL.
+
+> **Observation.** If `howTo` is present, `GET` it → not `404`. This is a `MUST` because a
+> dangling pointer out-competes the data beside it: a visitor holding a complete, sufficient
+> instruction object will follow a broken link and stop there. Nothing a signer needs may live
+> only behind that link.
+
+**AE-10.** An entry **MUST NOT** list a domain in `card.domains` that does not corroborate the
+claim. A verifier **MUST NOT** treat such a claim as established on the card alone: the domain
+must serve a DIF Well-Known DID Configuration at `/.well-known/did-configuration.json`
+containing a Domain Linkage Credential that verifies under `card.did` and carries a future
+expiry.
+
+> **Observation.** For each `d` in `card.domains`: `GET https://<d>/.well-known/did-configuration.json`
+> → `200`; at least one credential verifies under `card.did`; its `exp` is in the future.
+>
+> Note the direction, because it is easy to get backwards and the entry does not serve this
+> document. `domains` is a claim made *by* the entry and corroborated *by the domain*, whose
+> operator publishes the DID Configuration at its own root — which is precisely what makes it
+> evidence rather than a second self-assertion. Both halves are required: a claim the domain
+> does not corroborate is worse than no claim, because it reads as proof to anyone who checks
+> only the card. The expiry is required because a domain is leased, not owned: a credential with
+> no expiry keeps asserting a binding after the registration lapses, with no revocation channel
+> a third-party verifier is obliged to consult.
+
+### 4.3 The signed card envelope
+
+**AE-11.** The envelope's `sig` **MUST** verify under the DID that `envelope.card.did` names,
+over the canonical bytes of the envelope's signed fields.
+
+> **Observation.** Verify the signature against `envelope.card.did` using Ed25519. A plain
+> Agent Card is a self-assertion — anyone can serve a card claiming anyone's DID — so this
+> envelope is the only thing that makes a `did` → `url` binding evidence rather than a claim.
+
+**AE-12.** `envelope.ts` **MUST** be a JSON integer, and **MUST** be within **6 hours** of
+`now`, in both directions.
+
+> **Observation.** Assert `Number.isInteger(ts)` and `|now - ts| ≤ 21600`.
+>
+> Two independent reasons this is a `MUST`. A float `ts` is not reproducible across runtimes —
+> a number only one language serialises byte-for-byte is unverifiable everywhere else. And the
+> path is unauthenticated, so without a window the envelope is a harvestable bearer proof that
+> anyone who later takes over the address can replay. The symmetry matters: a `ts` far in the
+> future is refused too.
+
+**AE-13.** An entry **MUST NOT** sign a fresh envelope per request. It **SHOULD** re-sign at
+most hourly and serve a cached artifact.
+
+> **Observation.** Fetch the envelope twice in quick succession; `ts` and `sig` are unchanged.
+> An unauthenticated path that signs on demand is a signing oracle, and any stranger can drive
+> it.
+
+### 4.4 Methods, `Allow`, and the difference between 404 and 405
+
+**AE-14.** `OPTIONS` on any address the card names **MUST** answer `204` with an `Allow` header
+describing **that resource**, plus CORS preflight headers.
+
+> **Observation.** `OPTIONS` each advertised address → `204` with `Allow` present. Per RFC 9110
+> §10.2.1, `Allow` is a statement about the target, so the value differs per resource:
+> `GET, HEAD, OPTIONS` on the card paths; `GET, HEAD, POST, OPTIONS` on a mount that is both
+> the notice and the door; `POST, OPTIONS` on a guest mount's door.
+
+**AE-15.** A method not allowed on an **advertised** address **MUST** answer `405` carrying the
+same `Allow` header, and **MUST NOT** answer `404`.
+
+> **Observation.** `GET` a guest mount's door → `405` with `Allow: POST, OPTIONS`. The address
+> is signed into a public card, so hiding it conceals nothing; RFC 9110 §15.5.6 requires the
+> header.
+
+**AE-16.** A `POST` to a path the card does **not** name **MUST** answer `404`, not `405`.
+
+> **Observation.** `POST` to an unadvertised path → `404`. This is deliberate non-disclosure and
+> is not in tension with AE-15: what separates the two is where the address came from, not the
+> verb. An entry mounted beside other agents on one host must not confirm the existence of a
+> door at a **guessed** address.
+
+**AE-17.** A request whose HTTP request-target is in absolute form (carrying a scheme or an
+authority) **MUST** answer `404`, and the body **SHOULD** carry a `detail` naming the rule.
+
+> **Observation.** Send `POST http://elsewhere.example/x HTTP/1.1` → `404`.
+>
+> **Disclosed non-conformance.** RFC 9112 §3.2.2 says a server MUST accept absolute form. An
+> Agent Entry deliberately does not, because it answers exactly the address its card names and
+> that address has no second spelling. This is stated here rather than left to be discovered:
+> an undisclosed deliberate deviation costs an integrator an afternoon, which is why the body
+> carries a diagnostic instead of a bare `not found`.
+
+### 4.5 The message endpoint
+
+The request body is a JSON-RPC 2.0 call to `message/send` carrying an A2A `Message`. The signed
+payload is the canonical JSON of exactly six fields —
+`contextId`, `from`, `messageId`, `text`, `timestamp`, `to` — with keys sorted by Unicode code
+point, separators `,` and `:`, no whitespace, non-ASCII emitted literally, encoded UTF-8.
+`contextId` is JSON `null` when there is no conversation yet; it is still one of the six and is
+still signed. `sig` is base64 (standard alphabet, padded) of the 64-byte Ed25519 signature.
+
+**AE-18.** An entry **MUST** apply the checks below **in this order**, and **MUST** answer with
+the stated code. Order is normative: a later check must not be reachable when an earlier one
+fails.
+
+| # | Check | Failure |
+|---|---|---|
+| 1 | body ≤ 1 MiB | HTTP `413`, body not parsed |
+| 2 | body parses as a JSON object | HTTP `400` |
+| 3 | `method` is exactly the string `message/send` | `-32601` |
+| 4 | `params` and `params.message` are JSON objects (an array is not one) | `-32602` |
+| 5 | wire shape: `kind` is exactly `"message"`; text parts, `messageId` and `contextId` are strings (or `contextId` null); `metadata`, when present, is an object; `metadata.from`/`to`/`sig`, when present and non-null, are strings; no string carries a lone surrogate | `-32600` |
+| 6 | `text` ≤ 65536 UTF-8 bytes — **before any cryptography** | `-32005` |
+| 7 | `metadata.from`, `to` and `sig` are present (`null` reads as absent) | `-32001` |
+| 8 | `metadata.to` equals `<E>` | `-32003` |
+| 9 | `timestamp` is an integer within ±300 s of the entry's clock | `-32002` |
+| 10 | the signature verifies under `from` | `-32001` |
+| 11 | `messageId` not seen in the last 600 s | `-32002` |
+
+> **Observation.** Eleven requests, each violating exactly one row with every earlier row
+> satisfied; assert the code.
+>
+> **Two positions in this ladder are security properties, not preferences.**
+>
+> *Row 6 precedes any cryptography*, which is why an oversized message costs the entry nothing:
+> a size check placed after the signature is a check an attacker simply skips, and the
+> difference between a size limit and a denial-of-service amplifier is exactly this ordering.
+>
+> *Row 11 follows row 10*, and the reason is not obvious enough to leave unstated. Ahead of the
+> verify, an unauthenticated stranger could **burn a `messageId` its real sender was about to
+> use** — and because a replay table is necessarily capped and evicts oldest-first, that
+> stranger could flood past the cap to discard genuine entries and re-open real messages to
+> replay. Invalid signatures are not rate-limited, so that flood is free. Deduplicating before
+> authenticating turns a replay defence into a denial-of-service primitive aimed at the very
+> senders it protects.
+>
+> An implementation MAY deduplicate an **unsigned** request earlier (AE-29): there is no
+> signature to wait for, and nothing an attacker can burn on another party's behalf.
+
+**AE-19.** Every protocol verdict **MUST** be HTTP `200` carrying a JSON-RPC error object. Only
+`413` and `400` are non-`200`.
+
+> **Observation.** Each failing request from AE-18 rows 3-11 → HTTP `200` with `error.code` set.
+
+**AE-20.** An entry **MUST** answer a validly signed `message/send` from a DID it has never seen
+before, in the same HTTP response, with a reply signed by `<E>`. There **MUST NOT** be any
+registration, enrolment or approval step between a first contact and an answer.
+
+> **Observation.** Mint a fresh keypair; send one signed `message/send`; the response is HTTP
+> `200`, carries a message whose `metadata.from` is `<E>`, whose signature verifies under
+> `<E>`, which echoes the request's `contextId`, carries a fresh `messageId`, an integer
+> `timestamp` within ±300 s, and a `replyTo` naming the request's `messageId`.
+>
+> **This is the requirement the whole specification exists for**, and it is fully
+> stranger-verifiable: the verifier holds a key nobody has ever seen, performs no setup, and is
+> answered.
+
+**AE-21.** An entry **MUST NOT** echo caller-supplied text in an error response, and **MUST NOT**
+return an exception string, stack trace, field path or internal value to an unauthenticated
+caller.
+
+> **Observation.** Send a malformed request carrying a distinctive marker string; assert the
+> marker does not appear in the response, and that no response body carries a stack trace. A
+> caller that proved nothing is owed a verdict, not a diagnosis of the server.
+
+**AE-22.** An entry **MUST** answer every request with an HTTP response. An unhandled internal
+condition **MUST** produce `-32603`, never a closed socket.
+
+> **Observation.** A closed connection with no status line is not a verdict; to the sender it is
+> indistinguishable from a network fault, which is the one outcome a signed protocol cannot
+> diagnose.
+
+**AE-23.** The JSON-RPC `id` **MUST** be echoed when it is a String, a Number or Null, and
+**MUST** be answered under `null` otherwise (an object, an array, a string carrying a lone
+surrogate, or a number outside ±2^53).
+
+> **Observation.** Send each shape; assert the echoed `id`. The `id` is the one field no
+> signature covers and it is written straight back out, so a value two runtimes serialise
+> differently turns one verdict into two different responses.
+
+### 4.6 The refusal that teaches
+
+**AE-24.** When `metadata.from`, `to` and `sig` are **all** absent (AE-18 row 7), the `-32001`
+error **MUST** carry `data.accepts`: a JSON **array** whose first element is the same scheme
+object the card publishes under `agentEntry` (AE-8), verbatim.
+
+> **Observation.** `POST` a well-formed `message/send` with no `metadata`; assert `error.code`
+> is `-32001`, that `data.accepts` is an array, and that `data.accepts[0]` deep-equals the
+> card's `agentEntry` scheme object. One object, two surfaces — the menu and the door can never
+> advertise two different requirements.
+>
+> **The bar this is written to is behavioural, not informational:** *an agent holding only this
+> refusal, plus ordinary crypto tooling, can mint a `did:key`, sign correctly, and be answered
+> on its next POST.* That is why `recipient` is in the block — nobody can address a message
+> without it — and why the canonicalization rule is spelled out rather than named. It is an
+> array because "sign", "arrive with an introduction" and later "pay" are siblings in one
+> frame, not three bespoke refusals.
+
+**AE-25.** The refusal **MUST** remain a complete recipe with every URL removed from it.
+
+> **Observation.** Strip every URL-valued field from `data.accepts[0]`; what remains still names
+> the identifier derivation, the six signed fields, the canonicalization, the signature
+> encoding, the timestamp rule and the recipient. A visitor must never depend on fetching a
+> second document to answer the first.
+
+**AE-26.** A **partial** envelope — for example `from` and `to` present with `sig` stripped —
+**MUST NOT** receive `data.accepts`.
+
+> **Observation.** `POST` with `from` and `to` but no `sig`; assert `-32001` with no `accepts`
+> array. Whoever sent that already holds a key and already knows the shape, so it is a
+> downgrade attempt and not a walk-in; there is no reason to hand a prober a machine-readable
+> map of what to try next. A wrongly-*typed* field is row 5 (`-32600`), not row 7.
+
+### 4.7 Limits
+
+**AE-27.** An entry **MUST** cap `text` at 65536 UTF-8 bytes and the request body at 1 MiB.
+
+> **Observation.** AE-18 rows 1 and 6.
+
+**AE-28.** An entry **MUST** bound the rate at which it produces signed replies, in aggregate,
+and **MUST** refuse over-rate requests with `-32004` rather than by silence or by disconnection.
+
+> **Observation.** Drive the entry above its advertised ceiling from one signed identity and
+> assert the refusal carries `-32004` at HTTP `200`.
+>
+> The aggregate bound is the normative half, and the reason is arithmetic rather than policy:
+> a `did:key` costs nothing to mint, so a per-identity limit is not a bound at all. Free
+> identity defeats per-identity metering by definition; only the aggregate resists a flood. The
+> specific numbers are configuration, not conformance.
+
+**AE-29.** If an entry answers **unsigned** inquiries (an optional lane, **RECOMMENDED** to
+default off), that lane **MUST** be bounded entry-wide and **MUST NOT** be reachable at a
+higher rate than the signed lane's aggregate.
+
+> **Observation.** With the lane on, drive unsigned requests above the bound; assert refusal. An
+> unauthenticated caller must never become an unmetered signing oracle.
+
+---
+
+## 5. Relationship to other specifications
+
+An Agent Entry composes with the specifications below; none of them is an alternative to it,
+and a site may serve several at once. The distinctions here are about **layer**, not merit.
+
+**A2A.** This document is a profile of A2A, not a competitor. The card is an A2A Agent Card and
+the endpoint is A2A `message/send`. Everything added lives in extension objects and in
+`metadata`; no existing field changes meaning.
+
+**`llms.txt` and agent-facing sitemaps.** These *describe* a site to an agent. An Agent Entry
+*recognises* one. A description is read; an entry answers. They are complementary and a site
+should have both.
+
+**MCP (Model Context Protocol).** MCP is a transport between a host application and a tool
+server, and its authorization is OAuth-shaped: the party being identified is the **client
+application**. An Agent Entry identifies the **caller of an individual message**, on the
+message itself, with no session and no token. A site may run an MCP server and an Agent Entry
+simultaneously; they answer different questions and neither substitutes for the other.
+
+**OAuth Client ID Metadata Documents (CIMD).** CIMD identifies an OAuth client by an HTTPS URL
+which the authorization server fetches to obtain the client's metadata — replacing dynamic
+client registration with a document the client publishes. It answers *which software is this*,
+and it roots the answer in control of a domain name. An Agent Entry answers *who is knocking*,
+and roots the answer in possession of a key, demonstrated on every message.
+
+The two are not rivals; they are different layers, and the honest way to state the difference
+is to quote what each specification says about itself. A Client ID Metadata Document is
+unsigned by construction — an authorization server fetches JSON over TLS, and the draft's only
+identity check is that the `client_id` string equals the URL it was fetched from, compared with
+simple string comparison. The MCP authorization specification names the consequence directly:
+*"Client ID Metadata Documents cannot prevent `localhost` URL impersonation by themselves."*
+That is not a defect in CIMD; it is the boundary of what a fetched document can establish, and
+the OAuth ecosystem is addressing it in a separate attestation track.
+
+An Agent Entry sits on the other side of that boundary because possession is demonstrated at
+use time, per message, against an identifier that *is* the public key. What it correspondingly
+does **not** provide is what CIMD does well: a domain-rooted identity that an authorization
+server can hold policy against — allowlists, reputation, "if you trust `example.com` you trust
+this client". A deployment that needs both should run both.
+
+**RFC 9421 HTTP Message Signatures / Web Bot Auth.** These sign the HTTP *request* rather than
+the payload inside it, and are the natural companion where a signature must survive
+intermediaries or bind the transport itself. An Agent Entry MAY recognise such signatures in
+addition to the envelope specified here; doing so adds an observation and never changes a
+verdict reached under §4.
+
+---
+
+## 6. Security considerations
+
+**A card is a claim until it is bound.** Everything in §4.2 except AE-6 and AE-11 is
+self-asserted, and a byte-perfect copy of a legitimate card scores identically to the original
+on every check that does not include the signed `url`. AE-6 and AE-11 together are the only
+reason a `did` → `url` binding is evidence. An implementation that verifies the signature but
+skips the origin comparison has verified nothing useful: a valid envelope lifted from another
+site's endpoint passes every remaining check.
+
+**Do not render self-asserted names.** `name`, `description` and any logo on a card are written
+by whoever serves it. An interface that displays them to a human, next to a trust decision,
+has turned an unauthenticated string into a security control. Display the DID, and the domain
+when AE-10 corroborates it; show the friendly name only for entries a viewer has independently
+reason to trust. This is the single most reliable abuse channel in every deployed system of
+this shape, and it is not a corner case.
+
+**Free identity is not scarcity.** Minting a `did:key` costs nothing and requires no
+permission, which is a feature — it is what makes AE-20 possible. It also means being present
+in a ledger was never a bound on anything, which is why AE-28 requires the aggregate ceiling
+and treats the per-identity one as configuration.
+
+**An unauthenticated signing path is an oracle.** AE-13 exists because a stranger can drive any
+unauthenticated endpoint that signs on demand. Cache the artifact; re-sign on a timer.
+
+**Freshness is a security property, not hygiene.** AE-12's window bounds a harvestable proof.
+An envelope with no expiry is a bearer credential that outlives the operator's control of the
+address it names.
+
+**No human is claimed, and no human is claimed to be absent.** An Agent Entry answers a caller
+that may have no browser, no session and nobody at a keyboard — that is the case it exists for.
+Nothing in §4 asserts anything about human presence, and an implementation **MUST NOT** present a
+verified signature as evidence that a person authorised the message. It is evidence that a key
+did.
+
+The reason to state this rather than leave it implied is that the surrounding ecosystem is
+building machinery to sort interactive clients from headless ones, and a door that says nothing
+will have a meaning assigned to it. Two facts are worth carrying, because both come from the
+specifications doing that sorting. **Presence cannot be proven remotely today**: the strongest
+primitive in deployment is a WebAuthn gesture at one authenticator at one instant, whose own
+specification says it "does not give the Relying Party a concrete identification of the user";
+every artifact built above it is a bearer token that relays, and the party relaying it is
+precisely the one you were trying to distinguish. And **absence of a signal is not a signal**:
+the HTTP-signature draft this ecosystem runs on states it directly — a verifier that sees no
+signature "has learned nothing about the sender: not that it is automated, not that it is human,
+not that it is evading anything."
+
+So an entry **MUST NOT** treat the absence of a human-presence claim as evidence of automation,
+and **SHOULD NOT** treat the presence of one as evidence of a person. Where a site genuinely
+requires a human for an action, the mechanism already exists one layer up and does not belong
+here: an OAuth resource server can demand a fresh authentication event (RFC 9470), and a payment
+flow can refuse an autonomous mandate and ask for a directly approved one. Both are challenges
+that fall back to a person; neither is a proof carried on this wire.
+
+The engineering answer this specification prefers is to bound what an unattended caller can do
+rather than to interrogate whether it is unattended: a grant with a use count and an expiry, and
+a key binding that names what it is for, are checkable, and a presence claim is not.
+
+**Refusals leak.** AE-21 and AE-26 are both about what a prover is owed versus what a prober is
+owed. The keyless walk-in gets a complete recipe because refusing an agent for lacking a key
+nobody told it to make is the error, not the key. Everyone else gets a verdict.
+
+---
+
+## 7. Deliberately not normative here
+
+The behaviours below are real, are implemented, and are **not** `MUST`s in this document,
+because a third party cannot check them from outside. They are stated so that an implementer
+knows they exist and a reader knows they were not forgotten. Their oracle is the
+implementation's own test suite (§8), which is the right instrument for them — it has the
+access that a remote checker does not.
+
+- **The account ledger.** That a verified signature creates a durable row keyed by the
+  visitor's DID; that a second message from the same DID is the same account; that an unsigned
+  request creates no row at all; that a countersigned owner binding files several device keys
+  under one account. The *observable* half of this is AE-20, and AE-20 is where the normative
+  weight sits.
+- **Rate-limiter internals.** Whether a ceiling is per-account or entry-wide, the bucket
+  algorithm, and the specific numbers. AE-28 fixes the property that matters and leaves the
+  mechanism open.
+- **Storage and retention.** Ledger size caps, eviction, what is written to disk, what is
+  logged.
+- **The responder.** What produces the reply text — a fixed script, a database lookup, a
+  language model — is entirely the site's business and is invisible to this specification by
+  design.
+- **The observer hook.** That a per-message callback cannot delay or alter a reply.
+
+A note on the boundary, because it is the interesting part: several of these could be turned
+into remote observations by making the entry *report* on itself — an endpoint that says "this
+DID has an account". Every such endpoint is a new unauthenticated disclosure surface about
+third parties, and this specification declines to require one. The right answer to "can you
+prove your ledger works" is the implementation's test suite, not a public API that enumerates
+who has visited a site.
+
+---
+
+## 8. Verifying an implementation
+
+Two independent oracles, neither of which is this document, and both of which are needed for
+different reasons.
+
+**The implementation oracle — test vectors.** `conformance/run.mjs` and
+`conformance/vectors.json`, which ship inside the npm package, decide whether an implementation
+agrees with the fixed bytes: the canonical JSON, the signing payloads, the card envelopes and
+the `did:key` round-trips. `npm test` runs them with no network and nothing to ask anyone for.
+They prove an implementation matches the vectors. They cannot prove a deployment is real,
+because a test that imports the code it is testing establishes only that the code agrees with
+itself.
+
+**The interoperability evidence — two implementations, no shared code.** The requirements in §4
+are met today by two implementations written independently in different languages that share no
+code at all, held to identical verdicts by an acceptance suite that posts identical bytes to
+both — down to the HTTP framing — and requires the same status, the same account outcome and the
+same signed reply from each. That, rather than a shared library, is what makes the byte-level
+requirements here credible: a shared library would only ever have covered the parts the two
+happen to have in common. If you write a third implementation, that suite is the gate, and we
+will run it against yours on request.
+
+**The deployment oracle — a remote checker.** An implementation-blind checker dials a live
+origin over HTTP and decides requirements from the responses alone:
+
+```
+npx @muretai/agent-site-checker example.com
+```
+
+Use the package, not a hosted service. A specification whose conformance depends on an endpoint
+someone operates has acquired a runtime dependency on that operator, and the whole argument of
+§1 is that a normative claim should be checkable by a stranger with no relationship to anyone.
+The package runs locally, works against a local origin, and needs nothing from us.
+
+**How much of §4 it decides today, stated exactly.** The read-only requirements — discovery,
+the card, the signed envelope and its binding and freshness (roughly AE-1 through AE-13) — are
+decided by `GET`s and are what the checker covers now. The message-endpoint requirements
+(AE-14 onward) need a driver that *sends*: an eleven-request battery for AE-18, a fresh keypair
+for AE-20, a stripped envelope for AE-26. Those are decidable by a stranger — that is why they
+are `MUST`s — but a checker that POSTs to a stranger's endpoint is a different instrument from
+one that reads, and it should be run against your own deployment rather than someone else's. The
+gap between §9's table and what any given checker covers is a to-do list, not a licence: a `MUST`
+here is a requirement whether or not a tool currently checks it, and §9 exists so the gap is
+visible rather than convenient.
+
+**Reporting a divergence.** If the two oracles disagree, or if a requirement in §4 cannot be
+decided by its own Observation, that is a defect in this document. Please open an issue with
+the request and response bytes.
+
+---
+
+## 9. Requirement index
+
+Every normative statement, with the observation that decides it. A conforming implementation
+satisfies all `MUST` rows. This table is the document's contract with itself: a row that cannot
+be written is a requirement that does not belong in §4.
+
+| ID | Level | Requirement | Decided by |
+|---|---|---|---|
+| AE-1 | MUST | card served at the well-known path | `GET` → 200 + JSON |
+| AE-2 | MUST | legacy path is byte-identical | `GET` both, compare bytes |
+| AE-3 | MUST | signed envelope served | `GET` → 200 + JSON with `v/typ/card/ts/sig` |
+| AE-4 | MUST NOT | no unadvertised address answers | `GET`/`POST`/`OPTIONS` → 404 |
+| AE-5 | MUST | required card fields incl. `did` | parse + decode the DID |
+| AE-6 | MUST | `card.url` scope matches the dialled URL | compare origin + path prefix |
+| AE-7 | MUST | `open_door` under both names, identical | compare the two values |
+| AE-8 | MUST | terms stated on the card | parse `securitySchemes` |
+| AE-9 | MUST | `howTo` resolves, or is absent | `GET` it → not 404 |
+| AE-10 | MUST NOT | no uncorroborated `domains` claim | fetch the domain's DID configuration, verify, check expiry |
+| AE-11 | MUST | envelope verifies under `card.did` | Ed25519 verify |
+| AE-12 | MUST | `ts` integer, within ±6 h | parse + compare |
+| AE-13 | MUST NOT / SHOULD | no per-request signing; cache | fetch twice, compare `ts`/`sig` |
+| AE-14 | MUST | `OPTIONS` → 204 + per-resource `Allow` | `OPTIONS` each address |
+| AE-15 | MUST | 405 + `Allow` on advertised addresses | `GET` a guest door |
+| AE-16 | MUST | 404 (not 405) on unadvertised `POST` | `POST` a guessed path |
+| AE-17 | MUST | absolute-form target → 404 | send an absolute-form target |
+| AE-18 | MUST | eleven checks, in order, with fixed codes | eleven single-violation requests |
+| AE-19 | MUST | protocol verdicts are HTTP 200 | assert status on rows 3-11 |
+| AE-20 | MUST | unknown DID answered inline, signed, no registration | mint a key, send once, verify the reply |
+| AE-21 | MUST NOT | no echo of caller text, no internals | marker string + stack-trace scan |
+| AE-22 | MUST | always an HTTP response | assert a status line exists |
+| AE-23 | MUST | `id` echoed only when serialisable | send each `id` shape |
+| AE-24 | MUST | keyless refusal carries `accepts` | `POST` with no metadata, deep-equal the card block |
+| AE-25 | MUST | refusal survives URL removal | strip URLs, check completeness |
+| AE-26 | MUST NOT | partial envelope gets no `accepts` | `POST` with `sig` stripped |
+| AE-27 | MUST | size caps | oversized body and text |
+| AE-28 | MUST | aggregate reply ceiling, refused with `-32004` | drive above the ceiling |
+| AE-29 | MUST | unsigned lane bounded entry-wide | drive the anonymous lane |
+
+---
+
+## 10. IANA and registry considerations
+
+This document registers nothing. It uses the well-known URI `agent-card.json` established by
+the A2A specification under RFC 8615, the JSON-RPC 2.0 error range, and `did:key` as defined by
+the W3C DID method registry. The error codes in the range `-32001` … `-32005` and `-32010` …
+`-32011` are application-defined codes within the range JSON-RPC 2.0 reserves for
+implementation-defined server errors.
+
+## 11. Changes from the pre-specification implementation
+
+None. Version 1 describes behaviour already deployed; it introduces no new requirement that a
+running Agent Entry does not already satisfy. Where this document and the reference
+implementation disagree, that is a bug in one of them and a report is welcome — a specification
+written *after* the code has no excuse for describing something that was never shipped.