@muretai/agent-entry 1.5.0 → 1.6.1

package/README.md

@@ -111,7 +111,9 @@ 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 |
-| `name`, `description`, `version` | — | the card's own words. `description` is the line a person reads in a directory listing |
+| `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) |
+| `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 |
 
 `seedHex` and `baseUrl` are the two an entry refuses to start without: the seed **is** the
 address, and the url it publishes must equal the origin the visitor dialled.
@@ -198,7 +200,91 @@ cannot be told to look elsewhere:
 One round trip. No callback, no webhook, nothing to keep awake.
 
 `POST /` is exact — a POST anywhere else is 404. But **`GET /` is not taken**, so your home
-page stays exactly as it is. A site gives up three routes and nothing else.
+page stays exactly as it is.
+
+### The fourth step, and it is not optional
+
+Three routes make the door **work**. They do not make it **findable**, and those are separate
+problems with separate fixes.
+
+A visiting agent knows your domain, so it can guess the card path — but only if something told
+it there is an agent here at all. Normally that something is this module's own `GET /` notice.
+**If your pages are served by a different process than the door — a CDN, a static host, a
+framework, an edge worker — that notice never renders**, and your home page is HTML written for
+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:
+
+```
+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">
+```
+
+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
+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.
+
+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
+been answering signed messages correctly the whole time, at the address on that very page.
+
+Then check it from outside, because this is exactly the class of thing that looks installed:
+
+```bash
+curl -sI https://studio.example/ | grep -i '^link:'         # the header half
+curl -s  https://studio.example/ | grep 'rel/agent-entry'   # the tag half
+```
+
+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.
+
+### Check that your own CDN is not refusing your door
+
+The failure you are least likely to look for, because everything you control is correct.
+
+Most sites sit behind something that turns away suspicious traffic, and much of that judging is
+done on the **User-Agent** — which a client writes about itself, so the honest defaults are what
+get caught. Ours refused the default agent Python's standard library sends, and not only on the
+home page: on the **card** and on `POST /` too. The door was published, correct, and answering —
+to nobody using the stdlib client that "zero dependencies" produces.
+
+**The tell is the body of the refusal.** A door refuses in JSON and says how to qualify. An
+intermediary refuses in a line of plain text — `error code: 1010`, seventeen bytes, no `Link`, no
+card path, nothing a visitor can act on. If that is what strangers get, the door never saw them.
+
+**Do not check with `curl`.** It sends its own agent string and sails through, so "reproduce it
+with curl" turns a broken door into evidence that the visitor is at fault. Use a plain
+standard-library client, from outside your network:
+
+```bash
+UA='Python-urllib/3.11'   # or your language's default — the point is that it IS the default
+curl -s -A "$UA" -X POST https://studio.example/ -H 'content-type: application/json' \
+     -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{}}' | head -c 80
+```
+
+That must come back as JSON. Anything else is your edge, not your entry.
+
+**The exemption is simpler than it looks, and its shape is the point.** You never have to ask
+your CDN whether a caller is a bot — only to name three things it already knows: **host, method,
+path.** Because this door partitions by method, `POST /` and the card paths are exactly the
+surface to exempt, and your pages keep whatever protection they have. Write the rule with no
+user-agent field in it at all — the same rule the door lives by, one layer out.
+
+Two limits worth stating plainly. Some protections cannot be exempted by any rule at any tier;
+find out which yours is before promising yourself a carve-out. And **never let your CDN tell your
+responder who it is talking to** — some will forward a bot score or a "verified" flag to your
+origin, and if your origin is reachable without going through them (most are), that header is
+written by whoever dials it directly. Authority is the signature on the message; nothing else
+gets a vote.
 
 ### 1. A subdomain — the existing site is untouched
 
@@ -441,23 +527,14 @@ and it is not one. It is the upgrade path:
   can carry them.
 - **Statistics without a store: an analytics sink.** Nothing in the entry reads the
   ledger back to gate, greet or rate-limit, so a fire-and-forget sink records visiting
-  agents with no database anywhere. Your `responder` is handed the account DID; Google
-  Analytics 4 over the Measurement Protocol is one `fetch` inside it:
-
-  ```js
-  fetch('https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX'
-      + '&api_secret=' + process.env.GA_API_SECRET, {
-    method: 'POST',
-    body: JSON.stringify({ client_id: env.owner_did || env.peer_did,
-                           events: [{ name: 'agent_contact' }] }),
-  }).catch(() => {});   // analytics must never block a reply
-  ```
-
-  Keyed by `client_id`, GA tells new from returning visitors by itself — and a DID is a
-  public key, not personal data, though the record then lives with a third party, which
-  is your call. 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 on it.
+  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**,
+  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
+  on it.
 - **Revocation reaches you through your backend, not through this file.** An Agent Entry
   is deliberately network-free on the hot path: it never dials out while answering a
   visitor. Bindings carry an expiry, and a full node checks published revocations within
@@ -483,6 +560,84 @@ 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
+
+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
+or contributing to a profile of them.
+
+**Use `observer`, not your responder.** The door calls it once per message with the same
+envelope, after the verdict, so watching a visit stops being an edit to the code that decides
+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:
+
+- **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,
+  which is the only place it was ever offered to.
+
+**Salt the digest, and treat the salt as a secret.** A bare `sha256(did)` is a *stable global*
+pseudonym: anyone else who hashes the same DID gets the same string, so two properties could
+join their records on it. An HMAC under a secret only you hold makes the pseudonym meaningless
+anywhere else — the whole difference between "we count returning visitors" and "we helped build
+a profile".
+
+Google Analytics 4 over the Measurement Protocol, as an example of any sink:
+
+```js
+import crypto from 'node:crypto';
+
+const pseudonym = (did) =>
+  crypto.createHmac('sha256', process.env.PSEUDONYM_SALT).update(did).digest('hex').slice(0, 32);
+
+const observer = (env) => {
+  const account = env.owner_did || env.peer_did;
+  if (!account) return;                       // an unsigned walk-in is traffic, not a visitor
+  const first = (entry.ledger.get(account)?.messages ?? 1) === 1;
+
+  // `client_id` is the pseudonym, so the vendor can tell a returning visitor from a new one
+  // WITHOUT ever holding the DID that distinguishes them.
+  fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${GA_ID}&api_secret=${GA_SECRET}`, {
+    method: 'POST',
+    body: JSON.stringify({
+      client_id: pseudonym(account),
+      non_personalized_ads: true,
+      events: [{ name: 'agent_knock', params: { verified: env.verified ? 1 : 0,
+                                                first_contact: first ? 1 : 0,
+                                                intent: classify(env.text) }}],
+    }),
+  }).catch(() => {});                          // a dropped metric, never a dropped answer
+};
+```
+
+Four details there are load-bearing:
+
+- **`classify(env.text)`, never `env.text`.** Send *your own* bounded label, not what a stranger
+  typed. An attacker-chosen string must never become a dimension in your analytics.
+- **`.catch(() => {})` and no `await`.** Your door answers in one round trip; nothing on that
+  path may wait on somebody else's uptime. The `observer` contract already guarantees this — do
+  not lean on that generosity to be correct.
+- **Give it a timeout too** (an `AbortController` at a second or two). A hung connection is not
+  an error, so `catch` alone never fires.
+- **Say at boot whether the sink is on.** A sink silently off because a secret was never set
+  looks exactly like a sink that is on and receiving nothing, and a dashboard reading zero
+  cannot tell you which.
+
+**Say it on the card, because that is the surface your visitor reads.** Whatever you record, the
+party whose identifier it is arrives as an agent and will never open a privacy page written for
+people. Your card is fetched *before* the knock — that is the point of publishing terms up front
+— so it is the one place a visitor can learn what happens to its DID and still decide not to
+knock. Two or three sentences in `description`: what you keep, what leaves, what never does. A
+disclosure that arrives after the visit is not a disclosure, it is a receipt.
+
+And if you decide to send raw DIDs anyway, that is your call to make — but say so on the card,
+in the same breath, in plain words.
+
 ## Two implementations, pinned to each other
 
 This module is not alone. A Python reference implements the same contract, and the two are

package/muretai-agent-entry.mjs

@@ -2239,6 +2239,25 @@ export function canonicalMount(canonUrl, basePath) {
  *                  Recognition only ever ADDS identity (env.wba_did, the wbaVisits
  *                  count); it never changes verified, a ledger row, a rate lane or any
  *                  refusal verdict.
+ *   observer       OPTIONAL `(env) => void` — a WATCHER, called once per message with the
+ *                  same frozen envelope the responder gets. It exists so that OBSERVING a
+ *                  visit is not the same edit as ANSWERING one: wanting a counter should
+ *                  not mean reaching into the code that decides what to say.
+ *
+ *                  IT CANNOT AFFECT ANYTHING. It is called AFTER the verdict is settled,
+ *                  its return value is discarded, a thrown error is swallowed, and a
+ *                  promise is never awaited — so a slow or broken watcher cannot delay,
+ *                  fail, or change one byte of the signed reply. That is the whole contract
+ *                  and it is not a formality: this door answers in ONE round trip with no
+ *                  callback, and a watcher that dialled out on the hot path would make the
+ *                  visitor's answer depend on somebody else's uptime.
+ *
+ *                  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;
+ *                  if you need a metric, send a salted, site-scoped digest and keep the DID
+ *                  in your own store. This module ships no sink and names no vendor — the
+ *                  slot is here so an adapter can live outside it.
  */
 export function createAgentEntry({
   seedHex,
@@ -2258,6 +2277,7 @@ export function createAgentEntry({
   guest = false,
   maxAccounts = 50000,
   howToUrl = FIRST_KNOCK_URL,
+  observer = null,
   wbaVerifiers = null,
 } = {}) {
   if (!seedHex) throw new TypeError('createAgentEntry: seedHex is required');
@@ -2896,7 +2916,27 @@ export function createAgentEntry({
       wbaDid: wbaIdentify(reqHeaders) }), reqId, msg, from);
   }
 
+  /** Hand the envelope to the watcher, and make sure it can cost nothing.
+   *
+   *  Called BEFORE the responder on purpose: observing that a visit HAPPENED must not
+   *  depend on the answer succeeding, or the one request worth counting — the one where
+   *  the site's own code threw — is the one that goes uncounted.
+   *
+   *  Everything here is a refusal to let a watcher matter: the return value is discarded,
+   *  a synchronous throw is swallowed, and a returned promise is given a rejection handler
+   *  and then DROPPED rather than awaited. That last one is not tidiness — an unhandled
+   *  rejection can take a Node process down, so the watcher must not be able to end the
+   *  door by failing quietly in the background. */
+  function observe(env) {
+    if (typeof observer !== 'function') return;
+    try {
+      const r = observer(env);
+      if (isThenable(r)) r.then(undefined, () => {});
+    } catch { /* a watcher never changes what this door does */ }
+  }
+
   function respond(env, reqId, msg, toDid) {
+    observe(env);
     let answer;
     try {
       answer = responder(env);

package/package.json

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