@muretai/agent-entry 1.7.1 → 1.8.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` and `ua_family`, **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 |
 
@@ -145,6 +145,15 @@ 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.
+
 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
@@ -696,6 +705,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/muretai-agent-entry.mjs

@@ -2254,6 +2254,12 @@ 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` and
+ *                  `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. 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;
@@ -2509,7 +2515,9 @@ 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); }
@@ -2771,6 +2779,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 +2830,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 +2842,7 @@ 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,
               peer_did: null, owner_did: null, wba_did: null, text: null });
   }
 
@@ -3063,7 +3088,7 @@ 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,
               identified: env && env.peer_did ? 1 : 0 });
     let answer;
     try {
@@ -3211,24 +3236,6 @@ export function createAgentEntry({
       // and when this entry is mounted under a path, "anywhere else" INCLUDES the bare
       // host, which belongs to the site (or to the neighbour agent) and not to us.
       if (!isMountPath(pathname)) return jsonResponse(404, { error: 'not found' });
-      // A QUERY STRING MEANS THE POST IS NOT OURS. The door's address is the signed
-      // card's `url`, byte-exact: a base URL carrying a query is refused at startup, and
-      // a visitor's walk drops any query it was handed before it POSTs the card's `url` —
-      // so no conformant caller can arrive here, while a site's own query-multiplexed
-      // traffic (`?wc-api=`, `?wc-ajax=`, `?rest_route=`) always does. Disjoint BY
-      // CONSTRUCTION, which is what makes this a rule and not a heuristic. Measured:
-      // WooCommerce Stripe delivers its only webhook to `/?wc-api=wc_stripe` (path `/`,
-      // application/json); a bare-origin door that claimed it answered HTTP 200/-32601
-      // echoing the event id, the sender recorded the event as delivered and never
-      // retried — payment events lost SILENTLY. The answer is the unowned-path 404
-      // above, same bytes, one meaning — the DECISION(non-door-post-answers-404-not-405)
-      // non-disclosure again, because the caller most likely to land here is the site's
-      // own webhook, which deserves the most anonymous answer, never a door verdict.
-      const hashless = target.split('#')[0];
-      const queryAt = hashless.indexOf('?');
-      if (queryAt !== -1 && queryAt + 1 < hashless.length) {
-        return jsonResponse(404, { error: 'not found' });
-      }
       const buf = bodyBuffer || Buffer.alloc(0);
       const out = handlePost(buf, headers);
       // The stage is read off the finished answer, so an async responder tallies when it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muretai/agent-entry",
-  "version": "1.7.1",
+  "version": "1.8.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.