@muretai/agent-entry 1.8.0 → 1.10.0

package/README.md

@@ -105,6 +105,7 @@ answers questions and hands off nothing, is a signed claim you cannot keep.
 |---|---|---|
 | `skills` | `[]` | the menu above — what a visitor learns before knocking |
 | `openDoor` | `true` | publishes `agentEntry.open_door`: the field that tells a visiting agent it may message you with no introduction. The same fact is emitted under the older `muretai.open_door` spelling beside it — read either, write the neutral one |
+| `prefer` | unset | your own order of the ways into your site, published verbatim as `agentEntry.prefer` (spec AE-30): an array of `"page"`, `"card"`, `"mcp"` or `{kind, when}` with `when` one of `person`, `alone`, `key`, `no-key`, `token`, `browser` — e.g. `[{kind:'page', when:'no-key'}, 'card']` says "read on the page if you hold no key; otherwise the door". A visiting agent reads it against what it has on hand. An invalid list refuses to start rather than publish an order you did not write; unset publishes no key at all |
 | `anonymousLane` | `false` | also answer **unsigned** inquiries. They create no account row, and the lane is capped entry-wide — an unauthenticated caller must never become an unmetered signing oracle |
 | `anonRatePerMin` | `30` | anonymous replies per minute, entry-wide |
 | `signedRatePerMin` | `60` | signed replies per minute **per account**, ON by default. Attribution is not scarcity: a `did:key` costs nothing to mint, so being in your ledger was never a bound |
@@ -114,7 +115,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, 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) |
+| `observer` | none | called once per message with the same envelope your responder gets, plus `stage`, `identified`, `ua_family` and `client_class`, **after** the verdict — for counting, logging, analytics. It cannot matter: its return is discarded, a throw is swallowed, a promise is never awaited, so a slow or broken watcher cannot delay or change one byte of the signed reply. See [Counting visits](#counting-visits-without-handing-over-your-customer-list) |
 | `howToUrl` | none | a page a keyless visitor is pointed at as a worked example. **Empty means omitted** — the refusal already teaches the whole recipe without it, and a reference implementation must not stamp somebody else's docs host into every door built from it. Only set it to a URL you operate, and only after checking it resolves |
 | `name`, `description`, `version` | — | the card's own words. `description` is the line a person reads in a directory listing — and the right place to say what you record about visitors, since it is fetched **before** the knock |
 
@@ -131,12 +132,21 @@ door counts it:
 ```js
 entry.stats()
 // { gptbot:  { card_get: 12, signed_post: 3 },
-//   browser: { notice_get: 5 } }
+//   browser: { notice_get: 5, card_get: 2 } }
+
+entry.clientStats()
+// { 'declared-agent': { card_get: 12, signed_post: 3 },
+//   'human-like':     { notice_get: 5 },
+//   'stealth-agent':  { card_get: 2 } }
 ```
 
 Each request's `User-Agent` is classified into a fixed family (`claude-user`,
 `claudebot`, `gptbot`, `openai`, `perplexity`, `google-extended`, `muretai-node`,
-`curl`, `browser`, `none`/`other`) and counted by stage. In-process state like the
+`camoufox`, `playwright`, `puppeteer`, `selenium`, `headless-chrome`,
+`curl`, `browser`, `none`/`other`) and counted by stage. `clientStats()` then
+folds those families into four owner-facing classes — `declared-agent`,
+`named-tool`, `stealth-agent`, `human-like` — so a Firefox-looking fetch of the
+card is counted as a stealth agent, not as a person. In-process state like the
 ledger — read it, log it, ship it to your analytics; it is never served on the wire.
 Every caller also gets one nudge: `GET /` answers with a single `Link:` field carrying
 two relations — `rel="service-desc"` (RFC 8631) first, then the door pointer
@@ -154,6 +164,15 @@ five stages now carry it, refusals included, so "which clients got in and which
 is one query instead of two half-answers. Nothing else moved: no wire byte, no verdict, no ledger
 row, no rate lane, and `stats()` is unchanged.
 
+**Since 1.9.0 a Firefox-looking card fetch is not a human.** `stats()` still files it under
+`browser` — Camoufox's published shape is a clean Firefox UA, and that is the point of
+stealth. `clientStats()` splits it: a browser that only opened the notice is `human-like`;
+the same UA on the card or the door is `stealth-agent`; a leaking automation token
+(`playwright`, `camoufox`, …) is `named-tool`. Export `bodySignpost()` and put that
+`<a>` in the page body, because a snapshot client never sees the header or the
+`<head>` tag. Still observation only — the same POST with or without that UA is the
+same refusal.
+
 One rule holds this together, enforced by the contract suite rather than promised:
 **a User-Agent never affects `verified`, an account row, a rate limit, or any
 refusal.** A UA string is written by the client; a door that trusted it would be a
@@ -228,8 +247,8 @@ framework, an edge worker — that notice never renders**, and your home page is
 people with nothing machine-readable in it. The address ends up published in a card nobody was
 told to fetch.
 
-So put the pointer on every page a visitor might land on, in **both** spellings. Neither is a
-fallback for the other:
+So put the pointer on every page a visitor might land on, in **all three** spellings. None is a
+fallback for the others:
 
 ```
 Link: </.well-known/agent-card.json>; rel="https://muretai.net/rel/agent-entry"
@@ -237,13 +256,17 @@ Link: </.well-known/agent-card.json>; rel="https://muretai.net/rel/agent-entry"
 
 ```html
 <link rel="https://muretai.net/rel/agent-entry" href="/.well-known/agent-card.json">
+<a href="/.well-known/agent-card.json" rel="https://muretai.net/rel/agent-entry">This site answers agents at /.well-known/agent-card.json</a>
 ```
 
 The relation is an opaque **identifier**, matched as a string — nothing about resolving an agent
-endpoint requires a request to that host. The two spellings exist because the two kinds of client
+endpoint requires a request to that host. The three spellings exist because three kinds of client
 have opposite blind spots: an agent that fetches with a plain `curl` (no `-i`) never sees the
-header, and one that reads only headers never parses the HTML. Shipping one is a coin flip on
-which kind arrived.
+header; one that reads only headers never parses the HTML; and a snapshot / ARIA client
+(Camofox, Playwright accessibility dumps) sees only `<body>`, so the `<link>` in `<head>`
+vanishes too. Shipping one is a coin flip on which kind arrived. The module exports
+`bodySignpost()` so the body `<a>` is one function call, not a string you have to keep in
+sync with the relation URI.
 
 We know because we shipped one. An agent that had never been told about our door was handed only
 the domain, fetched the page, read the copy written for humans, and stopped — while the door had
@@ -253,13 +276,13 @@ Then check it from outside, because this is exactly the class of thing that look
 
 ```bash
 curl -sI https://studio.example/ | grep -i '^link:'         # the header half
-curl -s  https://studio.example/ | grep 'rel/agent-entry'   # the tag half
+curl -s  https://studio.example/ | grep 'rel/agent-entry'   # the tag half AND the body <a>
 ```
 
-Worth knowing before you call it done: **both halves disappear in a fetch that converts the page
-to markdown**, which is a common way an agent reads the web — headers are dropped and so is
-everything in `<head>`. No tag survives that. The only remedy is prose: say in the visible body
-that agents are answered here, and name the card path in text a reader can act on.
+Worth knowing before you call it done: **the header and the `<head>` tag disappear in a fetch
+that converts the page to markdown, and in an accessibility snapshot that only sees `<body>`**
+— a common way an agent browser reads the web. The body `<a>` is the spelling those clients
+can still see.
 
 ### Check that your own CDN is not refusing your door
 
@@ -359,7 +382,8 @@ node examples/server.mjs        # prints its DID and card URL
 Environment: `AGENT_ENTRY_SEED_HEX` (generated and printed if absent — **persist it, it is
 your site's identity**), `AGENT_ENTRY_PORT` (8788), `AGENT_ENTRY_BASE_URL`,
 `AGENT_ENTRY_NAME`, `AGENT_ENTRY_ANON` (`1` also accepts unsigned inquiries, which create
-no account).
+no account), `AGENT_ENTRY_PREFER` (your order of the ways in, as one JSON array — see
+`prefer` above; an invalid list refuses to start).
 
 ## What `baseUrl` may be
 

package/examples/server.mjs

@@ -43,6 +43,10 @@
  *                       https://example.com/agent) and answers NOTHING at `/` — no notice,
  *                       no OPTIONS, no POST. Point your proxy at the door path and the
  *                       well-known paths; the site keeps everything else, unchanged.
+ *   AGENT_ENTRY_PREFER     OPTIONAL: the site's own order of its ways in, as one JSON array
+ *                       (AE-30), e.g. '[{"kind":"page","when":"no-key"},"card"]' — "read on
+ *                       the page if you hold no key; otherwise the door". Published verbatim
+ *                       as `agentEntry.prefer`; an invalid list REFUSES to start.
  *   AGENT_ENTRY_WBA_JWKS   OPTIONAL: a JWKS document {"keys":[…]} as one JSON string —
  *                       the Web Bot Auth key directory (verified out of band) whose
  *                       holders this entry should RECOGNISE on inbound requests. Off
@@ -156,6 +160,10 @@ try {
     ...(process.env.AGENT_ENTRY_SIGNED_RATE_TOTAL
       ? { signedRatePerMinTotal: Number(process.env.AGENT_ENTRY_SIGNED_RATE_TOTAL) } : {}),
     guest: process.env.AGENT_ENTRY_GUEST === '1',
+    // AE-30: the site's own order of its ways in, a JSON array. Malformed JSON or an
+    // unknown kind/condition throws inside this try and the entry never starts — the same
+    // posture as a bad domain list: never publish a statement the operator did not make.
+    ...(process.env.AGENT_ENTRY_PREFER ? { prefer: JSON.parse(process.env.AGENT_ENTRY_PREFER) } : {}),
     wbaVerifiers,
   });
 } catch (err) {
@@ -183,17 +191,24 @@ const server = entry.listen(port, host, () => {
 // printed only when they changed. `[ua]` is greppable; the shape is entry.stats()
 // verbatim ({family: {stage: n}}). `unref()` so the timer never holds the process open.
 let lastStats = '';
+let lastClient = '';
 setInterval(() => {
   // Sorted keys at every level so the line is stable run to run (and diffable against
   // the Python runner's `json.dumps(..., sort_keys=True)` spelling of the same shape).
-  const line = JSON.stringify(entry.stats(), (k, v) =>
+  const stable = (obj) => JSON.stringify(obj, (k, v) =>
     (v && typeof v === 'object' && !Array.isArray(v))
       ? Object.fromEntries(Object.keys(v).sort().map((key) => [key, v[key]]))
       : v);
+  const line = stable(entry.stats());
   if (line !== '{}' && line !== lastStats) {
     console.log(`[ua] ${line}`);
     lastStats = line;
   }
+  const clientLine = stable(entry.clientStats());
+  if (clientLine !== '{}' && clientLine !== lastClient) {
+    console.log(`[client] ${clientLine}`);
+    lastClient = clientLine;
+  }
 }, 60_000).unref();
 
 // A port collision is the first thing anyone running this twice hits (a previous run that was

package/muretai-agent-entry.mjs

@@ -107,6 +107,17 @@ export const SIGNED_ENVELOPE_SCHEME = 'did-key-ed25519';
  *  examples/agent_entry_reference.py. */
 export const AGENT_ENTRY_REL = 'https://muretai.net/rel/agent-entry';
 
+/** The body `<a>` a site puts on its own front page so a snapshot / ARIA / `a[href]`
+ *  client (Camofox, Playwright accessibility dumps, markdown converters) can still find
+ *  the door. `<link rel>` in `<head>` and the HTTP `Link` header both vanish in those
+ *  views; an in-body anchor with this relation does not. `href` is the card path this
+ *  entry actually answers (mount-prefixed when the entry sits under a path). Must match
+ *  `body_signpost` in examples/agent_entry_reference.py. */
+export function bodySignpost(href = AGENT_CARD_PATH) {
+  const path = typeof href === 'string' && href ? href : AGENT_CARD_PATH;
+  return `<a href="${path}" rel="${AGENT_ENTRY_REL}">This site answers agents at ${path}</a>`;
+}
+
 /** Where a keyless visitor is sent to learn how to mint an identity and sign. It rides in
  *  the card AND in the refusal, so an agent that has only one of the two still has the URL.
  *
@@ -332,6 +343,16 @@ export const UA_FAMILIES = [
   ['perplexity', 'perplexity'],
   ['google-extended', 'google-extended'],
   ['muretai-node', 'muretai-node'],
+  // Leaking automation UAs. Must sit BEFORE `mozilla`: Camoufox/Playwright Firefox UAs
+  // start with "Mozilla/5.0 …" and a needle after that would never fire. A patched
+  // Camoufox sends a clean Firefox UA and classifies as `browser` — that is the
+  // stealth-agent case `clientClass` exists for, not a miss in this table.
+  ['camoufox', 'camoufox'],
+  ['camofox', 'camoufox'],
+  ['playwright', 'playwright'],
+  ['puppeteer', 'puppeteer'],
+  ['selenium', 'selenium'],
+  ['headlesschrome', 'headless-chrome'],
   ['curl', 'curl'],
   ['mozilla', 'browser'],
 ];
@@ -346,6 +367,20 @@ export const AI_AGENT_FAMILIES = new Set([
   'claude-user', 'claudebot', 'gptbot', 'openai', 'perplexity', 'google-extended',
 ]);
 
+/** Automation / HTTP-tool families that named themselves in the UA. OBSERVATION ONLY —
+ *  same rule as the rest of this table: never identity, never a verdict. Must match
+ *  `NAMED_TOOL_FAMILIES` in examples/agent_entry_reference.py. */
+export const NAMED_TOOL_FAMILIES = new Set([
+  'camoufox', 'playwright', 'puppeteer', 'selenium', 'headless-chrome', 'curl',
+]);
+
+/** The four owner-facing traffic classes `clientClass` may return. Bounded on purpose:
+ *  an attacker-chosen UA must never become a class name. Must match
+ *  `CLIENT_CLASSES` in examples/agent_entry_reference.py. */
+export const CLIENT_CLASSES = new Set([
+  'declared-agent', 'named-tool', 'stealth-agent', 'human-like',
+]);
+
 /** ASCII-only lowercase fold. NOT `toLowerCase()`: Unicode casing is runtime- and
  *  locale-shaped (the Turkish-I class of surprise), and no needle in the table needs it —
  *  folding only A-Z is what makes the same UA string classify identically in both twins. */
@@ -359,7 +394,7 @@ function asciiLower(s) {
 }
 
 /** UA string -> family. Absent/empty/non-string -> 'none'; no needle matched -> 'other'.
- *  Total on untrusted input, and the RETURN VALUE is always one of the twelve fixed
+ *  Total on untrusted input, and the RETURN VALUE is always one of the fixed
  *  family names — never a substring of the input (bounded stats keyspace). */
 export function uaFamily(ua) {
   if (typeof ua !== 'string' || !ua) return 'none';
@@ -370,6 +405,23 @@ export function uaFamily(ua) {
   return 'other';
 }
 
+/** Owner-facing traffic class. OBSERVATION ONLY — never `verified`, never a ledger row,
+ *  never a rate lane, never a refusal. The split an operator asked for: tell agent
+ *  traffic from human traffic WITHOUT treating a spoofable UA as a credential.
+ *
+ *  Camoufox / patched Playwright send a clean Firefox UA, so `uaFamily` says `browser`.
+ *  That is not a human reading the homepage. A human Firefox almost never GETs the
+ *  agent card or POSTs the door; a stealth agent that found the door does. The one
+ *  human-shaped case at the door is `browser` + `notice_get` (someone opened the
+ *  address as a document on a site-owning mount). Must match `client_class` in
+ *  examples/agent_entry_reference.py. */
+export function clientClass(family, stage) {
+  if (AI_AGENT_FAMILIES.has(family) || family === 'muretai-node') return 'declared-agent';
+  if (NAMED_TOOL_FAMILIES.has(family)) return 'named-tool';
+  if (family === 'browser' && stage === 'notice_get') return 'human-like';
+  return 'stealth-agent';
+}
+
 /** The FIRST User-Agent value out of a headers mapping, or null. Case-insensitive key
  *  scan so an in-process host can pass any casing; Node's own `req.headers` already
  *  lowercases keys and keeps only the FIRST user-agent of a duplicated pair — the Python
@@ -2096,6 +2148,43 @@ function domainFix(candidate) {
  * refuses every other bad value there. Truncating would start the entry with a claim that
  * is USABLE and NOT WHAT THEY SAID.
  */
+/** The kinds a visitor can take into a site, and the conditions a site may attach. Kept
+ *  identical to the visitor side (Agent Web Router `parsePrefer`): a kind or condition one
+ *  side knows and the other does not is a declaration one side silently drops. */
+export const PREFER_KINDS = ['page', 'card', 'mcp'];
+export const PREFER_WHEN = ['person', 'alone', 'key', 'no-key', 'token', 'browser'];
+
+/**
+ * The exact `agentEntry.prefer` this entry may publish, or a TypeError (AE-30).
+ *
+ * The site's own order of its ways in — "read on the page if you have no key, then the
+ * door", say. VALIDATED, NEVER REWRITTEN: this goes on a SIGNED card, and a card that says
+ * something the operator did not write is a worse card than none, so an unknown kind, an
+ * unknown condition or a stray key refuses the whole declaration instead of trimming it —
+ * the same posture as `canonicalDomains`. `null`/`undefined` means "not configured", and
+ * then no `prefer` key is published at all, which is what keeps an already-deployed
+ * entry's bytes unchanged.
+ */
+export function validatePrefer(prefer) {
+  if (prefer == null) return null;
+  if (!Array.isArray(prefer) || prefer.length === 0) {
+    throw new TypeError('agentEntry.prefer must be a non-empty array of "page" | "card" | "mcp" or {kind, when}');
+  }
+  for (const e of prefer) {
+    if (typeof e === 'string') {
+      if (!PREFER_KINDS.includes(e)) throw new TypeError(`agentEntry.prefer: unknown kind ${JSON.stringify(e)}`);
+      continue;
+    }
+    if (!e || typeof e !== 'object' || Array.isArray(e)) throw new TypeError('agentEntry.prefer: an entry must be a kind or {kind, when}');
+    const keys = Object.keys(e);
+    if (!PREFER_KINDS.includes(e.kind)) throw new TypeError(`agentEntry.prefer: unknown kind ${JSON.stringify(e.kind)}`);
+    if ('when' in e && !PREFER_WHEN.includes(e.when)) throw new TypeError(`agentEntry.prefer: unknown condition ${JSON.stringify(e.when)}`);
+    const stray = keys.filter((k) => k !== 'kind' && k !== 'when');
+    if (stray.length) throw new TypeError(`agentEntry.prefer: unexpected key(s) ${stray.join(', ')}`);
+  }
+  return prefer;
+}
+
 export function canonicalDomains(domains, { warn = true } = {}) {
   if (domains === undefined || domains === null) return [];
   if (!Array.isArray(domains)) {
@@ -2217,6 +2306,11 @@ export function canonicalMount(canonUrl, basePath) {
  *   responder      (envelope) => string | {text, contextId?, timestamp?} | Promise<…>
  *   openDoor       advertise `muretai.open_door` (default true) — the flag that tells a
  *                  visiting agent it may contact you without an introduction.
+ *   prefer         OPTIONAL: the site's own order of its ways in, published as
+ *                  `agentEntry.prefer` (AE-30) — e.g. `[{kind:'page', when:'no-key'}, 'card']`
+ *                  says "read on the page if you hold no key; otherwise the door". Validated
+ *                  by `validatePrefer`; an invalid list throws, so the entry never starts
+ *                  with a statement the operator did not make. Absent = no key published.
  *   anonymousLane  also accept UNSIGNED inquiries (default false). They create no account,
  *                  and the lane as a whole is capped at `anonRatePerMin` signed replies per
  *                  minute — it is unauthenticated, so it must not be an unmetered signing
@@ -2254,11 +2348,14 @@ 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
+ *                  WHAT IT IS TOLD. Every stage reports `stage`, `identified`,
  *                  `ua_family` — the door's own bounded classification of the client, one
  *                  of the fixed `UA_FAMILIES` names and NEVER a substring of what the caller
- *                  sent, so a stranger cannot write its own label into your metrics. The
- *                  POST stages add the envelope on top.
+ *                  sent, so a stranger cannot write its own label into your metrics — and
+ *                  `client_class`, the four-way split (`declared-agent` / `named-tool` /
+ *                  `stealth-agent` / `human-like`) that tells an operator whether a
+ *                  Firefox-looking knock is a stealth agent at the door or a human who
+ *                  opened the notice. The POST stages add the envelope on top.
  *
  *                  WHAT NOT TO PUT IN IT. The envelope carries `peer_did`/`owner_did`,
  *                  which a visitor handed you to transact with YOU. Forwarding a raw DID to
@@ -2275,6 +2372,7 @@ export function createAgentEntry({
   version = '1',
   responder = () => 'Thanks — a human will follow up.',
   openDoor = true,
+  prefer = null,
   anonymousLane = false,
   anonRatePerMin = ANON_RATE_PER_MIN,
   signedRatePerMin = SIGNED_RATE_PER_MIN,
@@ -2349,7 +2447,10 @@ export function createAgentEntry({
   // Neutral key first, vendor key beside it for one release. See the securitySchemes block
   // below for why the old spelling stays: a consumer must learn the new name BEFORE
   // producers stop emitting the old one, never after.
-  if (openDoor) card.agentEntry = { open_door: true };
+  // AE-30: the site's order rides on the NEUTRAL key only; the alias stays `open_door`
+  // alone, so an old consumer that compares the two aliases byte for byte keeps passing.
+  const canonPrefer = validatePrefer(prefer);
+  if (openDoor) card.agentEntry = { open_door: true, ...(canonPrefer ? { prefer: canonPrefer } : {}) };
   if (openDoor) card.muretai = { open_door: true };
   // Deliberately NO `relay`/`enc_pub` on the card: those advertise a store-and-forward
   // mailbox, and an agent entry has no listener draining one. Advertising a mailbox nobody
@@ -2498,6 +2599,7 @@ export function createAgentEntry({
   // composition to any stranger). Keyspace bounded by the fixed UA_FAMILIES table times
   // five stage names — an attacker choosing UA strings cannot grow it.
   const uaStats = new Map();
+  const clientStatsMap = new Map();
 
   /** Count the stage, and tell the watcher about it.
    *
@@ -2522,9 +2624,14 @@ export function createAgentEntry({
     let row = uaStats.get(family);
     if (!row) { row = new Map(); uaStats.set(family, row); }
     row.set(stage, (row.get(stage) || 0) + 1);
+    const cls = clientClass(family, stage);
+    let crow = clientStatsMap.get(cls);
+    if (!crow) { crow = new Map(); clientStatsMap.set(cls, crow); }
+    crow.set(stage, (crow.get(stage) || 0) + 1);
     if (typeof observer !== 'function') return;
     if (stage === 'card_get' || stage === 'notice_get') {
       observe({ stage, identified: 0, verified: false, ua_family: family,
+                client_class: cls,
                 peer_did: null, owner_did: null, wba_did: null, text: null });
     }
   }
@@ -2539,6 +2646,17 @@ export function createAgentEntry({
     return out;
   }
 
+  /** A plain JSON-able copy of the traffic-class counters: { class: { stage: n } }.
+   *  Same contract as `stats()`: in-process only, never on the wire, bounded keyspace. */
+  function clientStats() {
+    const out = {};
+    for (const [cls, row] of clientStatsMap) {
+      out[cls] = {};
+      for (const [stage, n] of row) out[cls][stage] = n;
+    }
+    return out;
+  }
+
   /** The `Link` header the notice route carries — the SAME one-field value for EVERY
    *  caller. TWO relations in ONE header field (RFC 8288 allows several link-values in
    *  one field, and one field is what keeps the two twins' bytes identical through their
@@ -2843,6 +2961,7 @@ export function createAgentEntry({
     if (typeof observer !== 'function' || lastRefusal === null) return;
     observe({ verified: false, refused: lastRefusal, stage: 'refused_post',
               identified: pendingStage === 'signed_post' ? 1 : 0, ua_family: pendingFamily,
+              client_class: clientClass(pendingFamily, 'refused_post'),
               peer_did: null, owner_did: null, wba_did: null, text: null });
   }
 
@@ -3089,6 +3208,7 @@ export function createAgentEntry({
     // 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,
+              client_class: clientClass(pendingFamily, pendingStage),
               identified: env && env.peer_did ? 1 : 0 });
     let answer;
     try {
@@ -3236,6 +3356,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
@@ -3367,9 +3505,10 @@ export function createAgentEntry({
 
   // `mount` is exported so a host app can route exactly what this entry answers (and log
   // it): it is derived, so reading it here can never disagree with the signed card.
-  // `stats` is the owner-facing UA-family counters and `wbaVisits` the DID->count of
-  // WBA-verified fetches — both in-process only, like `ledger`.
-  return { did, card, ledger, mount, stats, wbaVisits,
+  // `stats` is the owner-facing UA-family counters, `clientStats` the four-way
+  // traffic-class split, and `wbaVisits` the DID->count of WBA-verified fetches —
+  // all in-process only, like `ledger`.
+  return { did, card, ledger, mount, stats, clientStats, wbaVisits,
     handleRequest, handleRequestAsync, listen,
     cardEnvelope: () => JSON.parse(cardEnvelopeBytes().toString('utf8')) };
 }

package/package.json

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

package/spec/v1.md

@@ -396,6 +396,25 @@ 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.
 
+**AE-30.** An entry **MAY** publish `agentEntry.prefer`: the site's own order of its ways in
+for a visiting agent. It is an array whose entries are a kind — `"page"`, `"card"`, `"mcp"` —
+or an object `{"kind": <kind>, "when": <condition>}` with `when` one of `person`, `alone`,
+`key`, `no-key`, `token`, `browser`, read by the visitor against what it has on hand. When
+published it **MUST** appear under the neutral `agentEntry` key exactly as the operator
+declared it (validated, not rewritten), and **MUST** appear identically in the signed
+envelope's inner card. The legacy `muretai` alias **MUST NOT** carry it. When not configured,
+the card **MUST NOT** carry a `prefer` key. A declaration that fails validation **MUST** make
+the entry refuse to start rather than publish a corrected or partial order.
+
+> **Observation.** Start an entry with a declaration; `GET` the card and the envelope; assert
+> `agentEntry.prefer` equals the declaration in both and `muretai` has no `prefer`. Start one
+> without; assert no `prefer` key. Start one with `["teleport"]`; assert it exits non-zero and
+> binds nothing. Why refuse rather than fix: a signed card is the origin's statement, and a
+> statement the operator did not make is a worse card than none — the same posture as a bad
+> `domains` list. Why the visitor's conditions live here: which way in a stranger should try
+> first is the site's design (read on the page, become a counterparty later — or knock first),
+> and the card is the one place the site can say so that a page script cannot rewrite.
+
 ---
 
 ## 5. Relationship to other specifications
@@ -629,6 +648,7 @@ be written is a requirement that does not belong in §4.
 | 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 |
+| AE-30 | MAY / MUST | `agentEntry.prefer` verbatim on card + envelope, or absent; invalid refuses to start | `GET` both, compare; start with a bad list → exit ≠ 0 |
 
 ---