@muretai/agent-entry 1.6.3 → 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 |
 
@@ -138,10 +138,21 @@ 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
 ledger — read it, log it, ship it to your analytics; it is never served on the wire.
-An AI-agent family also gets one nudge: `GET /` answers it with
-`Link: </.well-known/agent-card.json>; rel="service-desc"` (RFC 8631), so a crawler
-that landed on prose is handed the machine-readable door. The body stays
-byte-identical for every caller.
+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
+`rel="https://muretai.net/rel/agent-entry"` — so a crawler that landed on prose is
+handed the machine-readable door, whatever its `User-Agent` claims. The body stays
+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
@@ -694,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

@@ -336,10 +336,12 @@ export const UA_FAMILIES = [
   ['mozilla', 'browser'],
 ];
 
-/** The families that read as an AI agent — the ones the notice route signposts with a
- *  `Link` header. `muretai-node` is deliberately absent: its Outbox already walks the
- *  well-known card paths, so a signpost buys it nothing. Must match the same set in
- *  examples/agent_entry_reference.py. */
+/** The families that read as an AI agent. Since v1.11 this set steers NO wire byte —
+ *  the notice route's `Link` signpost is emitted for every caller (see `steerHeaders`
+ *  and ISSUE(agent-entry-unconditional-link)) — so it remains only as a published
+ *  classification an operator's own observation code can lean on. `muretai-node` is
+ *  deliberately absent: its Outbox already walks the well-known card paths. Must match
+ *  the same set in examples/agent_entry_reference.py. */
 export const AI_AGENT_FAMILIES = new Set([
   'claude-user', 'claudebot', 'gptbot', 'openai', 'perplexity', 'google-extended',
 ]);
@@ -1706,7 +1708,7 @@ function jsonResponse(status, obj, extraHeaders = {}) {
   };
 }
 
-function rpcError(id, error, data) {
+function baseRpcError(id, error, data) {
   const err = { ...error };
   if (data) err.data = data;
   return jsonResponse(200, { jsonrpc: '2.0', id: id ?? null, error: err });
@@ -2252,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;
@@ -2394,6 +2402,18 @@ export function createAgentEntry({
     },
   };
   card.security = [{ [SIGNED_ENVELOPE_SCHEME]: [] }];
+  // WHERE A 1.0-NATIVE READER FINDS THE ENDPOINT. A2A 1.0 removed the top-level `url` /
+  // `preferredTransport` pair in favour of `supportedInterfaces`, so a client written
+  // against 1.0 greps for exactly this field and, without it, learns nothing from this
+  // card about where to POST. `url` is doorUrl — the address message/send is actually
+  // POSTed to, the same string the securitySchemes `exampleRequest`'s `endpoint` names —
+  // and deliberately NOT canonUrl, which at a bare origin differs from the door by the
+  // trailing slash (canonUrl's bytes are pinned and signed; this entry is what carries
+  // the canonical POST form). Appended last so every field an already-deployed entry
+  // publishes keeps its bytes AND its position.
+  card.supportedInterfaces = [
+    { url: doorUrl, protocolBinding: 'JSONRPC', protocolVersion: PROTOCOL_VERSION },
+  ];
 
   const cardBytes = Buffer.from(JSON.stringify(card), 'utf8');   // identical bytes on both paths
   // ACCOUNT DID -> {first_seen, last_seen, messages}. Keyed by the RESOLVED account (T102):
@@ -2479,10 +2499,34 @@ export function createAgentEntry({
   // five stage names — an attacker choosing UA strings cannot grow it.
   const uaStats = new Map();
 
+  /** Count the stage, and tell the watcher about it.
+   *
+   *  Every stage a visitor can reach already passes through here — `card_get`, `notice_get`,
+   *  `anon_post`, `signed_post`, `refused_post` — so this is where the observer learns HOW FAR
+   *  somebody got. It could previously see only the conversations: a site shipping visits to
+   *  analytics got the answered messages and nothing else, no card fetch, no notice read, no
+   *  keyless walk-in. The interesting shape of agent traffic is exactly that drop-off — how
+   *  many looked, how many tried, how many got in.
+   *
+   *  Reported from HERE and not from a second place, so the watcher and `entry.stats()` can
+   *  never disagree about what happened, and a stage added later is reported without anyone
+   *  remembering to. `identified` rides along because "no DID at all" and "had a DID and was
+   *  refused" are different answers for a site deciding whether to open the anonymous lane.
+   *
+   *  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.
+   *  `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);
+    if (typeof observer !== 'function') return;
+    if (stage === 'card_get' || stage === 'notice_get') {
+      observe({ stage, identified: 0, verified: false, ua_family: family,
+                peer_did: null, owner_did: null, wba_did: null, text: null });
+    }
   }
 
   /** A plain JSON-able copy of the counters: { family: { stage: n } }. */
@@ -2495,25 +2539,32 @@ export function createAgentEntry({
     return out;
   }
 
-  /** The `Link` header the notice route carries. TWO relations with different audiences,
-   *  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 single-header plumbing):
+  /** 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
+   *  single-header plumbing):
    *
-   *    - the DOOR pointer, `rel="https://muretai.net/rel/agent-entry"`, for EVERY caller.
-   *      This is the coexistence primitive (E4): an agent that fetched a page finds the
+   *    - `rel="service-desc"` (RFC 8631's registered relation for "service description …
+   *      primarily intended for consumption by machines"), FIRST. It was emitted only to
+   *      the UA families that read as an AI agent (the T119 signpost) until a
+   *      third-party scanner (agentcard.org, 2026-08-21) measured that conditioned
+   *      emission as invisible: its crawler is none of our families, so a working door
+   *      scored as publishing no service description at all — the revisit trigger
+   *      recorded in ISSUE(agent-entry-unconditional-link). A header conditioned on a
+   *      guess about the reader is invisible to exactly the readers the guess missed,
+   *      so it is now emitted for every caller.
+   *    - the DOOR pointer, `rel="https://muretai.net/rel/agent-entry"`. This is the
+   *      coexistence primitive (E4): an agent that fetched a page finds the
    *      machine-readable door in the RESPONSE, with no HTML to parse and no prose to
    *      read, and a browser ignores it — which is what lets a site keep its own front
    *      page and add ONE header instead of migrating. An absolute URI because RFC 8288
    *      §2.1.2 permits a bare token only for an IANA-registered relation.
-   *    - `rel="service-desc"` (RFC 8631's registered relation for "service description …
-   *      primarily intended for consumption by machines"), FIRST and only for the UA
-   *      families that read as an AI agent — the T119 signpost, unchanged in meaning.
    *
-   *  HEADER-ONLY on purpose: the notice BODY is byte-identical for every caller, so what
-   *  the UA changes is still only this one additive relation and never a verdict. */
-  function steerHeaders(family) {
+   *  HEADER-ONLY on purpose: the notice BODY is byte-identical for every caller, and now
+   *  so is this header — the UA family still steers observation (`tally`/`stats`), never
+   *  a byte on the wire. */
+  function steerHeaders(family) {   // `family` kept for observation symmetry, unread here
     const door = `<${mount}${AGENT_CARD_PATH}>; rel="${AGENT_ENTRY_REL}"`;
-    if (!AI_AGENT_FAMILIES.has(family)) return { Link: door };
     return { Link: `<${mount}${AGENT_CARD_PATH}>; rel="service-desc", ${door}` };
   }
 
@@ -2718,7 +2769,97 @@ export function createAgentEntry({
    * size checks come BEFORE any parsing or crypto — a check placed after the signature is
    * a check the attacker simply skips.
    */
+  /** The code of the refusal this request produced, or null when it was answered. Set by the
+   *  entry-local `rpcError` below so the funnel can report it without re-parsing a Buffer. */
+  let lastRefusal = null;
+
+  /** The stage `tally()` computed for the POST currently in flight, handed to whichever
+   *  observation point reports it. `tally()` runs AFTER the ladder returns, so the answered
+   *  case is observed before this is set — which is why `respond()` reads it lazily rather
+   *  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. */
+  const rpcError = (id, error, data) => {
+    lastRefusal = error && typeof error.code === 'number' ? error.code : null;
+    return baseRpcError(id, error, data);
+  };
+
+  /** Every POST outcome, observed once, at the single point they all funnel through.
+   *
+   *  `respond()` observes the answered case with the full envelope. Everything else — the
+   *  keyless walk-in, the bad signature, the flood that hit a ceiling — returned an rpcError
+   *  and was never seen at all, so a door could count who it TALKED to and never who it TURNED
+   *  AWAY. For a site asking whether agents are arriving, the refusals are the signal: an agent
+   *  that could not get in is the one nobody hears from again. It also made the documented
+   *  contract false, since the guide says the observer runs once per message, after the verdict,
+   *  and a refusal IS a verdict.
+   *
+   *  Structural rather than enumerated ON PURPOSE. Seventeen refusal sites would have been
+   *  seventeen chances to forget, and the eighteenth would be forgotten by construction.
+   *
+   *  The code is read from `lastRefusal`, set by `rpcError` on its way out, rather than by
+   *  re-parsing the response — the body is already a Buffer by then, and a watcher must never
+   *  cost a JSON round-trip on the reply path.
+   *
+   *  A refusal hands the watcher only what was actually established: `refused` carries the
+   *  JSON-RPC code and the DIDs are null, because a walk-in that named nobody named nobody. The
+   *  watcher still cannot matter — same swallowed throw, same discarded return. */
   function handlePost(rawBody, reqHeaders) {
+    lastRefusal = null;
+    // The stage a POST reaches is decided by whether it CARRIED a signature, which is knowable
+    // from the request alone — so it is settled here, before the ladder answers, and read by
+    // 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();
+    return out;
+  }
+
+  /** The answered case is already observed inside `respond()`; this adds refusals only, so no
+   *  message is ever observed twice. */
+  function observeRefusal() {
+    if (typeof observer !== 'function' || lastRefusal === null) return;
+    observe({ verified: false, refused: lastRefusal, stage: 'refused_post',
+              identified: pendingStage === 'signed_post' ? 1 : 0, ua_family: pendingFamily,
+              peer_did: null, owner_did: null, wba_did: null, text: null });
+  }
+
+  /** Did this POST body carry a signature? That is the whole difference between a keyless
+   *  walk-in and an identified visitor, and it is answerable from the request without waiting
+   *  for the verdict — a bad signature is still a visitor who HAD a key. Parsed defensively:
+   *  anything unreadable is a walk-in, because it certainly did not present an identity. */
+  function postRequestStage(rawBody) {
+    try {
+      const buf = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody || '');
+      const req = JSON.parse(buf.toString('utf8'));
+      const meta = req?.params?.message?.metadata;
+      return (meta && typeof meta.sig === 'string' && meta.sig) ? 'signed_post' : 'anon_post';
+    } catch { return 'anon_post'; }
+  }
+
+  function handlePostLadder(rawBody, reqHeaders) {
     // RAW BYTES, always. A host app that hands us a decoded string has already destroyed
     // the evidence the strict decode below exists to find, so normalise once and measure
     // the SIZE in bytes rather than in UTF-16 code units.
@@ -2871,18 +3012,26 @@ export function createAgentEntry({
     if (!Number.isSafeInteger(ts) || Math.abs(nowEpoch() - ts) > CLOCK_WINDOW_S) {
       return rpcError(reqId, ERRORS.REPLAY_REJECTED, 'timestamp out of range (clock skew or replay)');
     }
-    // 7. duplicate messageId inside the replay window. (Its type was settled by the shape
-    //    gate: a non-string messageId never reaches here on either implementation.)
+    // 7. the signature itself, under the key DERIVED FROM `from`. (`messageId`'s type was
+    //    settled by the shape gate: a non-string never reaches here on either implementation.)
     const messageId = msg.messageId;
-    if (!replay.checkAndRemember(messageId)) {
-      return rpcError(reqId, ERRORS.REPLAY_REJECTED, 'duplicate messageId (replay) detected');
-    }
-    // 8. the signature itself, under the key DERIVED FROM `from`.
     const fields = { from, to, messageId, contextId: msg.contextId ?? null,
       timestamp: ts, text, sig };
     if (!verifyEnvelope(fields, { recipientDid: did })) {
       return rpcError(reqId, ERRORS.UNAUTHENTICATED, 'signature does not match');
     }
+    // 8. duplicate messageId inside the replay window — AFTER the verify, and the ORDER is the
+    //    property. The table is state an authenticated sender depends on, so a caller who has
+    //    proved nothing must not write into it. Ahead of the verify a stranger could BURN an id
+    //    its real sender was about to use, and because the table is capped and evicts
+    //    oldest-first, 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. This is the
+    //    rule the signed lane's ceiling already follows one step below, for the same reason; it
+    //    was simply never applied here. The cost of the swap is one Ed25519 verify spent on a
+    //    replayed VALID message, which an attacker must first have obtained.
+    if (!replay.checkAndRemember(messageId)) {
+      return rpcError(reqId, ERRORS.REPLAY_REJECTED, 'duplicate messageId (replay) detected');
+    }
 
     // 9. T102 account layer. An OPTIONAL countersigned v2 binding collapses an owner's device
     //    DIDs to ONE account; a present-but-INVALID binding fails closed with the SAME
@@ -2936,18 +3085,22 @@ export function createAgentEntry({
   }
 
   function respond(env, reqId, msg, toDid) {
-    observe(env);
+    // 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, ua_family: pendingFamily,
+              identified: env && env.peer_did ? 1 : 0 });
     let answer;
     try {
       answer = responder(env);
     } catch (e) {
-      return rpcError(reqId, ERRORS.INTERNAL_ERROR, `responder failed: ${e && e.message}`);
+      return rpcError(reqId, ERRORS.INTERNAL_ERROR, 'the site backend failed to answer');
     }
     const inbound = { contextId: msg.contextId ?? null, messageId: msg.messageId ?? null };
     if (isThenable(answer)) {
       return answer.then(
         (v) => finishReply(reqId, v, { inbound, toDid }),
-        (e) => rpcError(reqId, ERRORS.INTERNAL_ERROR, `responder failed: ${e && e.message}`));
+        (e) => rpcError(reqId, ERRORS.INTERNAL_ERROR, 'the site backend failed to answer'));
     }
     return finishReply(reqId, answer, { inbound, toDid });
   }
@@ -3055,8 +3208,8 @@ export function createAgentEntry({
         return { status: 200,
           headers: { 'Content-Type': 'text/plain; charset=utf-8',
             'Content-Length': String(body.length),
-            // The ONE wire-visible thing observation adds: an AI-agent UA is pointed at
-            // the machine-readable door. The body above is byte-identical either way.
+            // Every caller is pointed at the machine-readable door — the same one-field
+            // Link value for all of them (v1.11). The body above is byte-identical too.
             ...steerHeaders(family) },
           body };
       }
@@ -3180,7 +3333,7 @@ export function createAgentEntry({
         const body = oversize ? oversizeSentinel() : Buffer.concat(chunks, total);
         Promise.resolve()
           .then(() => handleRequestAsync(req.method, req.url, req.headers, body))
-          .catch((e) => rpcError(null, ERRORS.INTERNAL_ERROR, String(e && e.message)))
+          .catch(() => rpcError(null, ERRORS.INTERNAL_ERROR, 'the entry failed to answer'))
           .then(({ status, headers, body: out }) => {
             res.writeHead(status, headers);
             res.end(req.method === 'HEAD' ? undefined : out);

package/package.json

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