@muretai/agent-entry 1.6.2 → 1.7.1

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-who-they-are) |
+| `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) |
 | `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,12 @@ 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.
 
 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
@@ -534,8 +536,8 @@ and it is not one. It is the upgrade path:
   ledger back to gate, greet or rate-limit, so a fire-and-forget sink records visiting
   agents with no database anywhere. Use `observer` for it, never your responder: watching
   a visit should not be an edit to the code that decides what to say. See
-  [Counting visits](#counting-visits-without-handing-over-who-they-are) below for the
-  whole pattern, including the one rule that shapes it — **a DID is not a page view**,
+  [Counting visits](#counting-visits-without-handing-over-your-customer-list) below for the
+  whole pattern, including the one rule that shapes it — **a DID is not a cookie**,
   so what leaves your box is a salted digest, never the identifier itself. A sink cannot
   be read back during a request: it counts customers, it cannot recognise one. It
   replaces a log line, not the store above — none of the recommended features stand
@@ -565,7 +567,7 @@ What the entry now handles for you at the HTTP layer, so you do not have to:
   which says a server must accept the absolute form: this endpoint answers exactly the
   address its card names, and the refusal says so.
 
-## Counting visits without handing over who they are
+## Counting visits without handing over your customer list
 
 You will want to know how many agents knocked, how many came back, and what they asked. All
 three are answerable — and how you answer them decides whether you are counting your visitors
@@ -576,11 +578,18 @@ envelope, after the verdict, so watching a visit stops being an edit to the code
 what to say. It cannot matter: its return is discarded, a throw is swallowed, a promise is
 never awaited — a slow or broken watcher cannot delay or change one byte of the signed reply.
 
-**The rule that shapes everything else: a DID is not a page view.** A visitor hands you one in
-order to transact with **you**, and here first contact *is* the account — there is no signup
-form where they agreed to anything else. Forwarding the raw value to an analytics vendor shares
-a durable identifier its owner never offered them, silently, on a surface with no consent
-dialog and no visitor who could decline. So split it:
+**The rule that shapes everything else: a DID is not a cookie, and it is not a throwaway
+either.** Nobody imposed it — the visitor read your card *before* knocking, and an owner who
+wanted this conversation kept apart would have sent a different agent, because an owner runs
+several and each is a distinct agent with its own lasting identity. But the one that did knock
+means to keep the key it used: that is how it gets recognised, introduced and trusted anywhere on
+the network, so it is closer to a professional's name than to a tracking cookie.
+
+Which is exactly why the raw value should not travel onward. **The DID is genuinely durable, and
+you were given it so that YOU could reach them again.** Widen that purpose and nothing happens to
+you legally, which is the part worth understanding: the owner simply stops sending that agent to
+you. Silently, at no cost, and you never learn you lost them — not one data point, the whole
+relationship. So split it:
 
 - **What leaves** — a salted digest and a few shape facts. Never the DID, never the text.
 - **What stays** — the relationship (who, how many, first and last seen) in your own store,

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 });
@@ -2394,6 +2396,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 +2493,32 @@ 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. */
   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 +2531,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 +2761,80 @@ 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;
+
+  /** 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);
+    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,
+              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 +2987,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 +3060,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,
+              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 +3183,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 };
       }
@@ -3083,6 +3211,24 @@ 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
@@ -3180,7 +3326,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.2",
+  "version": "1.7.1",
   "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",