@muretai/agent-entry 1.2.1 → 1.4.0

package/README.md

@@ -6,7 +6,7 @@ It verifies who is knocking, opens an account for them, and answers — in the s
 response. No signup form, because the visitor's key already is the account. When that
 person replaces their phone, your site still knows it is them.
 
-One file. Zero dependencies. Node 20+.
+One file. Zero dependencies. No database. Node 20+.
 
 **Running in production — check it yourself, right now:**
 
@@ -69,6 +69,101 @@ resolves it and files them under `owner_did`, so a replaced phone is not a new c
 Your entry does not need to poll or be told: a node that carries the account learns it on
 its own, and refuses that key.
 
+## Say what your door answers
+
+A visiting agent reads your card **before** it knocks. Left alone, that card says something
+answers here and nothing about what it answers, so the visitor has to guess and learns your
+menu only from whatever comes back when it guesses wrong.
+
+```js
+createAgentEntry({
+  seedHex, name: 'Example Studio', baseUrl: 'https://studio.example', responder,
+  skills: [{
+    id: 'ask',
+    name: 'signed-answers-about-the-studio',
+    description: 'Ask what a shoot costs, what the studio does, and how to book. '
+      + 'The answer comes back in the same HTTP response, signed by this domain.',
+    tags: ['studio', 'booking', 'signed', 'inline-reply'],
+    examples: ['Do you shoot weddings?', 'What does a half-day cost?', 'How do I book?'],
+  }],
+});
+```
+
+It is an A2A `AgentSkill` list, so an agent that already speaks A2A reads it without being
+taught anything new, and it goes into the plain card **and** the signed envelope — the menu
+is signed too.
+
+Two rules worth holding yourself to. **Every example must be answerable:** an example is a
+promise printed on your card, and the visitor who copies one verbatim is the best-behaved
+visitor you will get, so drive your examples through your own responder in your tests.
+**Declare only what the responder does:** a skill that mentions booking, on an entry that
+answers questions and hands off nothing, is a signed claim you cannot keep.
+
+### The rest of the settings
+
+| option | default | what it does |
+|---|---|---|
+| `skills` | `[]` | the menu above — what a visitor learns before knocking |
+| `openDoor` | `true` | publishes `muretai.open_door`: the field that tells a visiting agent it may message you with no introduction |
+| `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. Signed senders are not bound by it: they are attributable and already in your ledger |
+| `maxAccounts` | `50000` | how many accounts the in-process ledger holds |
+| `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 |
+
+`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.
+
+## Who is knocking — observation, never identity
+
+The person who found you often never opens a browser: they hand your link to their
+agent, and the agent fetches your card and knocks. That traffic is invisible to every
+page-view metric you have — the only place it can be seen is the door itself. So the
+door counts it:
+
+```js
+entry.stats()
+// { gptbot:  { card_get: 12, signed_post: 3 },
+//   browser: { notice_get: 5 } }
+```
+
+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.
+
+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
+door anyone could talk their way through.
+
+### From hint to proof: recognising signed crawlers (Web Bot Auth)
+
+Major AI crawlers now **sign** their requests (HTTP Message Signatures, RFC 9421).
+Hand your entry the public keys you trust — the body of a key directory you fetched
+and verified out of band — and it verifies them, with no network call at answer time:
+
+```js
+createAgentEntry({
+  seedHex, name, baseUrl, responder,
+  wbaVerifiers: { keys: [{ kty: 'OKP', crv: 'Ed25519', x: '…' }] },
+});
+```
+
+A verified fetch is counted (`entry.wbaVisits`); a verified message hands your
+responder `env.wba_did` — the identity whose key signed the *request*, beside
+`env.peer_did`, the identity that signed the *message*. The same rule holds:
+recognition never changes a verdict, mints no account, and lifts no rate limit. A
+signature over the transport proves who fetched — not who wrote the text, and a
+captured header set is replayable until it expires (minutes), which is why `wba_did`
+is identification, never authorship.
+
 ## Install
 
 ```bash
@@ -82,6 +177,13 @@ which is the point — you can read all of it before you trust it.
 curl -O https://raw.githubusercontent.com/muretai/agent-entry/main/muretai-agent-entry.mjs
 ```
 
+That is the whole footprint. **There is no database to install** and no schema to create —
+an entry runs, in production, on its bounded in-process state, which is how muretai.com's
+own door runs. Once your door is answering, a store of your own is the **recommended**
+upgrade — the ledger is your customer list, and more features stand on keeping it — while
+an analytics tool covers statistics without one. Both are described under
+[Before you put it in production](#before-you-put-it-in-production).
+
 ## Put one on a site you already have
 
 A visiting agent knows only your **domain**, so the three paths it walks are fixed — it
@@ -323,12 +425,39 @@ makes the visitor someone you can recognise the next time.
 
 ## Before you put it in production
 
-Two things this reference implementation deliberately leaves to you, both called out in
-the source:
-
-- **Persist the ledger and the device→owner pins.** The sample keeps them in memory, so a
-  restart forgets which owner a device belongs to and trusts the next claim it sees. A
-  real site puts both in its own database, keyed by exactly the account DID it is handed.
+**Nothing here is needed to start** — an entry runs, and every exchange stays correct,
+on its in-process state alone; some installers have read this section as a prerequisite,
+and it is not one. It is the upgrade path:
+
+- **Recommended — persist the ledger in a store of your own: it is your customer list.**
+  Every row is keyed by a customer's DID, which is their address: what you need to
+  recognise a returning customer and to contact them again later. In memory that list
+  evaporates on restart. Kept in the database your site already has — keyed by exactly
+  the account DID you are handed — it is what the features beyond answering stand on:
+  greeting a returning account by its history, following up on yesterday's inquiry,
+  pricing by relationship. Keep the device→owner pins and the replay guard beside it and
+  the security rules — a device is never re-owned, a message is never accepted twice —
+  survive restarts as well; those two are read on every message, so only a real store
+  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.
 - **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

package/examples/server.mjs

@@ -4,7 +4,7 @@
  *
  * **This is a usage SAMPLE, not part of core Muretai.** It adds nothing to the protocol:
  * it only wires the public primitive `createAgentEntry()` from
- * `web/agent-entry/muretai-agent-entry.mjs` to a demo booking desk. Copy it, gut the responder,
+ * `muretai-agent-entry.mjs` to a demo booking desk. Copy it, gut the responder,
  * point it at your backend — core stays byte-unchanged.
  *
  * Run it:
@@ -33,6 +33,17 @@
  *   AGENT_ENTRY_NAME       public display name on the card
  *   AGENT_ENTRY_HOST       bind address (default 127.0.0.1 — set 0.0.0.0 only behind TLS)
  *   AGENT_ENTRY_ANON       "1" also accepts UNSIGNED walk-in inquiries (they mint no account)
+ *   AGENT_ENTRY_GUEST      "1" = GUEST MOUNT: coexist with a site that keeps its own front
+ *                       page. The entry serves its card paths and the POST door named by
+ *                       AGENT_ENTRY_BASE_URL (which must then carry that path, e.g.
+ *                       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_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
+ *                       when absent. Recognition only ADDS identity (env.wba_did);
+ *                       it never changes a verdict.
  */
 
 import { createAgentEntry, newSeedHex, didFromSeedHex, trimOuter, AGENT_CARD_PATH }
@@ -76,6 +87,11 @@ function responder(env) {
   // the account", and that is invisible if the ledger only lives in memory: an operator
   // watching this log is how you SEE a stranger's identity appear, and how you tell an
   // anonymous walk-in (no account) from a verified first contact (an account) at a glance.
+  // `[WBA]` is the transport-level identity (T107): the request's HTTP signature named a
+  // key we were configured to recognise — identification, never authorship of the text.
+  if (env.wba_did) {
+    console.log(`[WBA]         transport signed by ${env.wba_did}`);
+  }
   // NOTE for anyone copying this file: `ledger` here is a **Map** (the Python reference in
   // examples/agent_entry_reference.py uses a dict) — use .get()/.size, not obj[key]/Object.keys.
   // The row is written BEFORE the backend is called, so `messages === 1` means "this very
@@ -107,6 +123,17 @@ function responder(env) {
 // tells a site operator nothing.
 let entry;
 try {
+  // A malformed AGENT_ENTRY_WBA_JWKS refuses to start, same posture as a bad domain
+  // list: silently starting without the keys the operator named only looks protective.
+  let wbaVerifiers = null;
+  if (process.env.AGENT_ENTRY_WBA_JWKS) {
+    try {
+      wbaVerifiers = JSON.parse(process.env.AGENT_ENTRY_WBA_JWKS);
+    } catch {
+      throw new TypeError('AGENT_ENTRY_WBA_JWKS is not valid JSON — paste the key '
+        + 'directory body ({"keys":[…]}) as one JSON string');
+    }
+  }
   entry = createAgentEntry({
     seedHex,
     name,
@@ -116,6 +143,8 @@ try {
     responder,
     openDoor: true,                                     // "you may contact me, no introduction"
     anonymousLane: process.env.AGENT_ENTRY_ANON === '1',
+    guest: process.env.AGENT_ENTRY_GUEST === '1',
+    wbaVerifiers,
   });
 } catch (err) {
   console.error(err && err.message ? err.message : String(err));
@@ -132,8 +161,29 @@ const server = entry.listen(port, host, () => {
   }
   console.log(`  Listening on ${host}:${port} — POST a signed message/send to `
     + `${entry.mount || '/'}`);
+  if (process.env.AGENT_ENTRY_GUEST === '1') {
+    console.log(`  Guest mount: the site keeps GET / — this entry answers the card at `
+      + `${AGENT_CARD_PATH} (and under ${entry.mount}) and POST ${entry.mount} only`);
+  }
 });
 
+// The observation counters, surfaced the way the ledger is: on this runner's stdout,
+// 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 = '';
+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) =>
+    (v && typeof v === 'object' && !Array.isArray(v))
+      ? Object.fromEntries(Object.keys(v).sort().map((key) => [key, v[key]]))
+      : v);
+  if (line !== '{}' && line !== lastStats) {
+    console.log(`[ua] ${line}`);
+    lastStats = line;
+  }
+}, 60_000).unref();
+
 // A port collision is the first thing anyone running this twice hits (a previous run that was
 // backgrounded and orphaned, usually). An unhandled 'error' event prints a Node stack trace,
 // which tells a site operator nothing — say what happened and what to do instead.