@muretai/agent-entry 1.8.0 → 1.9.0

package/README.md

@@ -114,7 +114,7 @@ answers questions and hands off nothing, is a signed claim you cannot keep.
 | `domains` | none | the domains this entry speaks for (see below) |
 | `basePath` | from `baseUrl` | the path this entry answers at, derived rather than set beside it |
 | `wbaVerifiers` | none | a JWKS document (`{"keys":[…]}`) of Ed25519 keys whose holders this entry should **recognise** on inbound signed requests (Web Bot Auth / RFC 9421 — see *Who is knocking*). Recognition only adds `env.wba_did` and a visit count; it never changes a verdict |
-| `observer` | none | called once per message with the same envelope your responder gets, 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 +131,21 @@ door counts it:
 ```js
 entry.stats()
 // { gptbot:  { card_get: 12, signed_post: 3 },
-//   browser: { notice_get: 5 } }
+//   browser: { notice_get: 5, card_get: 2 } }
+
+entry.clientStats()
+// { 'declared-agent': { card_get: 12, signed_post: 3 },
+//   'human-like':     { notice_get: 5 },
+//   'stealth-agent':  { card_get: 2 } }
 ```
 
 Each request's `User-Agent` is classified into a fixed family (`claude-user`,
 `claudebot`, `gptbot`, `openai`, `perplexity`, `google-extended`, `muretai-node`,
-`curl`, `browser`, `none`/`other`) and counted by stage. In-process state like the
+`camoufox`, `playwright`, `puppeteer`, `selenium`, `headless-chrome`,
+`curl`, `browser`, `none`/`other`) and counted by stage. `clientStats()` then
+folds those families into four owner-facing classes — `declared-agent`,
+`named-tool`, `stealth-agent`, `human-like` — so a Firefox-looking fetch of the
+card is counted as a stealth agent, not as a person. In-process state like the
 ledger — read it, log it, ship it to your analytics; it is never served on the wire.
 Every caller also gets one nudge: `GET /` answers with a single `Link:` field carrying
 two relations — `rel="service-desc"` (RFC 8631) first, then the door pointer
@@ -154,6 +163,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 +246,8 @@ framework, an edge worker — that notice never renders**, and your home page is
 people with nothing machine-readable in it. The address ends up published in a card nobody was
 told to fetch.
 
-So put the pointer on every page a visitor might land on, in **both** spellings. Neither is a
-fallback for the other:
+So put the pointer on every page a visitor might land on, in **all three** spellings. None is a
+fallback for the others:
 
 ```
 Link: </.well-known/agent-card.json>; rel="https://muretai.net/rel/agent-entry"
@@ -237,13 +255,17 @@ Link: </.well-known/agent-card.json>; rel="https://muretai.net/rel/agent-entry"
 
 ```html
 <link rel="https://muretai.net/rel/agent-entry" href="/.well-known/agent-card.json">
+<a href="/.well-known/agent-card.json" rel="https://muretai.net/rel/agent-entry">This site answers agents at /.well-known/agent-card.json</a>
 ```
 
 The relation is an opaque **identifier**, matched as a string — nothing about resolving an agent
-endpoint requires a request to that host. The two spellings exist because the two kinds of client
+endpoint requires a request to that host. The three spellings exist because three kinds of client
 have opposite blind spots: an agent that fetches with a plain `curl` (no `-i`) never sees the
-header, and one that reads only headers never parses the HTML. Shipping one is a coin flip on
-which kind arrived.
+header; one that reads only headers never parses the HTML; and a snapshot / ARIA client
+(Camofox, Playwright accessibility dumps) sees only `<body>`, so the `<link>` in `<head>`
+vanishes too. Shipping one is a coin flip on which kind arrived. The module exports
+`bodySignpost()` so the body `<a>` is one function call, not a string you have to keep in
+sync with the relation URI.
 
 We know because we shipped one. An agent that had never been told about our door was handed only
 the domain, fetched the page, read the copy written for humans, and stopped — while the door had
@@ -253,13 +275,13 @@ Then check it from outside, because this is exactly the class of thing that look
 
 ```bash
 curl -sI https://studio.example/ | grep -i '^link:'         # the header half
-curl -s  https://studio.example/ | grep 'rel/agent-entry'   # the tag half
+curl -s  https://studio.example/ | grep 'rel/agent-entry'   # the tag half AND the body <a>
 ```
 
-Worth knowing before you call it done: **both halves disappear in a fetch that converts the page
-to markdown**, which is a common way an agent reads the web — headers are dropped and so is
-everything in `<head>`. No tag survives that. The only remedy is prose: say in the visible body
-that agents are answered here, and name the card path in text a reader can act on.
+Worth knowing before you call it done: **the header and the `<head>` tag disappear in a fetch
+that converts the page to markdown, and in an accessibility snapshot that only sees `<body>`**
+— a common way an agent browser reads the web. The body `<a>` is the spelling those clients
+can still see.
 
 ### Check that your own CDN is not refusing your door
 

package/examples/server.mjs

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

package/muretai-agent-entry.mjs

@@ -107,6 +107,17 @@ export const SIGNED_ENVELOPE_SCHEME = 'did-key-ed25519';
  *  examples/agent_entry_reference.py. */
 export const AGENT_ENTRY_REL = 'https://muretai.net/rel/agent-entry';
 
+/** The body `<a>` a site puts on its own front page so a snapshot / ARIA / `a[href]`
+ *  client (Camofox, Playwright accessibility dumps, markdown converters) can still find
+ *  the door. `<link rel>` in `<head>` and the HTTP `Link` header both vanish in those
+ *  views; an in-body anchor with this relation does not. `href` is the card path this
+ *  entry actually answers (mount-prefixed when the entry sits under a path). Must match
+ *  `body_signpost` in examples/agent_entry_reference.py. */
+export function bodySignpost(href = AGENT_CARD_PATH) {
+  const path = typeof href === 'string' && href ? href : AGENT_CARD_PATH;
+  return `<a href="${path}" rel="${AGENT_ENTRY_REL}">This site answers agents at ${path}</a>`;
+}
+
 /** Where a keyless visitor is sent to learn how to mint an identity and sign. It rides in
  *  the card AND in the refusal, so an agent that has only one of the two still has the URL.
  *
@@ -332,6 +343,16 @@ export const UA_FAMILIES = [
   ['perplexity', 'perplexity'],
   ['google-extended', 'google-extended'],
   ['muretai-node', 'muretai-node'],
+  // Leaking automation UAs. Must sit BEFORE `mozilla`: Camoufox/Playwright Firefox UAs
+  // start with "Mozilla/5.0 …" and a needle after that would never fire. A patched
+  // Camoufox sends a clean Firefox UA and classifies as `browser` — that is the
+  // stealth-agent case `clientClass` exists for, not a miss in this table.
+  ['camoufox', 'camoufox'],
+  ['camofox', 'camoufox'],
+  ['playwright', 'playwright'],
+  ['puppeteer', 'puppeteer'],
+  ['selenium', 'selenium'],
+  ['headlesschrome', 'headless-chrome'],
   ['curl', 'curl'],
   ['mozilla', 'browser'],
 ];
@@ -346,6 +367,20 @@ export const AI_AGENT_FAMILIES = new Set([
   'claude-user', 'claudebot', 'gptbot', 'openai', 'perplexity', 'google-extended',
 ]);
 
+/** Automation / HTTP-tool families that named themselves in the UA. OBSERVATION ONLY —
+ *  same rule as the rest of this table: never identity, never a verdict. Must match
+ *  `NAMED_TOOL_FAMILIES` in examples/agent_entry_reference.py. */
+export const NAMED_TOOL_FAMILIES = new Set([
+  'camoufox', 'playwright', 'puppeteer', 'selenium', 'headless-chrome', 'curl',
+]);
+
+/** The four owner-facing traffic classes `clientClass` may return. Bounded on purpose:
+ *  an attacker-chosen UA must never become a class name. Must match
+ *  `CLIENT_CLASSES` in examples/agent_entry_reference.py. */
+export const CLIENT_CLASSES = new Set([
+  'declared-agent', 'named-tool', 'stealth-agent', 'human-like',
+]);
+
 /** ASCII-only lowercase fold. NOT `toLowerCase()`: Unicode casing is runtime- and
  *  locale-shaped (the Turkish-I class of surprise), and no needle in the table needs it —
  *  folding only A-Z is what makes the same UA string classify identically in both twins. */
@@ -359,7 +394,7 @@ function asciiLower(s) {
 }
 
 /** UA string -> family. Absent/empty/non-string -> 'none'; no needle matched -> 'other'.
- *  Total on untrusted input, and the RETURN VALUE is always one of the twelve fixed
+ *  Total on untrusted input, and the RETURN VALUE is always one of the fixed
  *  family names — never a substring of the input (bounded stats keyspace). */
 export function uaFamily(ua) {
   if (typeof ua !== 'string' || !ua) return 'none';
@@ -370,6 +405,23 @@ export function uaFamily(ua) {
   return 'other';
 }
 
+/** Owner-facing traffic class. OBSERVATION ONLY — never `verified`, never a ledger row,
+ *  never a rate lane, never a refusal. The split an operator asked for: tell agent
+ *  traffic from human traffic WITHOUT treating a spoofable UA as a credential.
+ *
+ *  Camoufox / patched Playwright send a clean Firefox UA, so `uaFamily` says `browser`.
+ *  That is not a human reading the homepage. A human Firefox almost never GETs the
+ *  agent card or POSTs the door; a stealth agent that found the door does. The one
+ *  human-shaped case at the door is `browser` + `notice_get` (someone opened the
+ *  address as a document on a site-owning mount). Must match `client_class` in
+ *  examples/agent_entry_reference.py. */
+export function clientClass(family, stage) {
+  if (AI_AGENT_FAMILIES.has(family) || family === 'muretai-node') return 'declared-agent';
+  if (NAMED_TOOL_FAMILIES.has(family)) return 'named-tool';
+  if (family === 'browser' && stage === 'notice_get') return 'human-like';
+  return 'stealth-agent';
+}
+
 /** The FIRST User-Agent value out of a headers mapping, or null. Case-insensitive key
  *  scan so an in-process host can pass any casing; Node's own `req.headers` already
  *  lowercases keys and keeps only the FIRST user-agent of a duplicated pair — the Python
@@ -2254,11 +2306,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
@@ -2498,6 +2553,7 @@ export function createAgentEntry({
   // composition to any stranger). Keyspace bounded by the fixed UA_FAMILIES table times
   // five stage names — an attacker choosing UA strings cannot grow it.
   const uaStats = new Map();
+  const clientStatsMap = new Map();
 
   /** Count the stage, and tell the watcher about it.
    *
@@ -2522,9 +2578,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 +2600,17 @@ export function createAgentEntry({
     return out;
   }
 
+  /** A plain JSON-able copy of the traffic-class counters: { class: { stage: n } }.
+   *  Same contract as `stats()`: in-process only, never on the wire, bounded keyspace. */
+  function clientStats() {
+    const out = {};
+    for (const [cls, row] of clientStatsMap) {
+      out[cls] = {};
+      for (const [stage, n] of row) out[cls][stage] = n;
+    }
+    return out;
+  }
+
   /** The `Link` header the notice route carries — the SAME one-field value for EVERY
    *  caller. TWO relations in ONE header field (RFC 8288 allows several link-values in
    *  one field, and one field is what keeps the two twins' bytes identical through their
@@ -2843,6 +2915,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 +3162,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 +3310,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 +3459,10 @@ export function createAgentEntry({
 
   // `mount` is exported so a host app can route exactly what this entry answers (and log
   // it): it is derived, so reading it here can never disagree with the signed card.
-  // `stats` is the owner-facing UA-family counters and `wbaVisits` the DID->count of
-  // WBA-verified fetches — both in-process only, like `ledger`.
-  return { did, card, ledger, mount, stats, wbaVisits,
+  // `stats` is the owner-facing UA-family counters, `clientStats` the four-way
+  // traffic-class split, and `wbaVisits` the DID->count of WBA-verified fetches —
+  // all in-process only, like `ledger`.
+  return { did, card, ledger, mount, stats, clientStats, wbaVisits,
     handleRequest, handleRequestAsync, listen,
     cardEnvelope: () => JSON.parse(cardEnvelopeBytes().toString('utf8')) };
 }

package/package.json

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