@muretai/agent-entry 1.0.0 → 1.2.0

package/README.md

@@ -8,6 +8,9 @@ person replaces their phone, your site still knows it is them.
 
 One file. Zero dependencies. Node 20+.
 
+Questions are welcome — mention [@muretaiai](https://x.com/muretaiai) on X, or
+[open an issue](https://github.com/muretai/agent-entry/issues).
+
 ```js
 import { createAgentEntry } from '@muretai/agent-entry';
 
@@ -144,9 +147,124 @@ 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).
 
+## What `baseUrl` may be
+
 `baseUrl` must be the URL visitors actually dial: it is what your signed card claims, and
 a card naming a different origin proves nothing about yours.
 
+Agent Entry does not copy it into the card — it canonicalises it, so the string it signs is
+the one a visitor computes from the URL they dialled. Where the two could differ, **it
+refuses to start**, naming the rule and the value to paste instead. That is deliberate: the
+alternative is a card that fails on a stranger's machine, where the only diagnostic is
+"signature verification failed" and nothing at all appears on yours.
+
+Tidied up for you: surrounding spaces, the case of the scheme and host, a default port
+(`:443`, `:80`), a trailing dot on the host, and any trailing slashes.
+`https://studio.example/` and `https://Studio.Example:443` both publish as
+`https://studio.example`.
+
+Refused, with the fix in the message: a scheme other than `http`/`https`, a missing host,
+`user@host`, a query string, a `#` fragment, non-ASCII characters, a stray tab or space, a
+backslash, `.` or `..` in the path **including their `%2e` spellings**, a broken `%` escape,
+and a port outside 1–65535.
+
+> **Upgrading from 1.1.x?** The `%2e` rule is new. A `baseUrl` like
+> `https://shop.example/a/%2e%2e/support` used to start on the Python reference and now
+> refuses on both — because a browser's URL parser removes those segments and Python's does
+> not, so the address you publish and the address a visitor computes were already two
+> different things. The refusal names the string to paste instead. **Check your `baseUrl`
+> before you deploy:** this turns a running entry into one that will not boot.
+
+Two rules worth knowing before you pick a URL:
+
+- **Paths are case-sensitive.** `https://studio.example/Alice` and `.../alice` are different
+  sites to a visitor. Choose one spelling and use it in every link, invite and QR code.
+- **Write an international domain in its `xn--` form** — `https://xn--eckwd4c7c.example`,
+  not the Unicode spelling — and publish your links in that same form. JavaScript's URL
+  parser punycodes a host and Python's does not, so the two implementations would otherwise
+  sign different bytes for the same site.
+
+## One host, many agents
+
+A domain can hold a **fleet** — a front desk, support, sales — each its own agent, its own
+key, its own address, each contactable directly. Give each one a `baseUrl` that carries its
+path:
+
+```js
+createAgentEntry({ seedHex: SUPPORT_SEED, name: 'Support',
+                   baseUrl: 'https://studio.example/support', responder });
+```
+
+Every route then hangs off that path — `GET /support/.well-known/agent-card.json`, the
+signed envelope beside it, and `POST /support` — and **the bare host is a 404 for that
+entry**. On a shared host the bare host belongs to your site or to a neighbour, and an entry
+that answered there would be answering for someone else.
+
+The mount is **derived from `baseUrl`**, never configured beside it, so the address the
+router answers on and the address the signed card claims are the same string by
+construction. Two settings would let you spell them differently, and that produces the worst
+error message this system has: every visitor fails with *"cannot prove that … owns …"* and
+nothing says why.
+
+A visitor handed `https://studio.example/support` reaches support and **only** support. If
+sales re-served support's genuine, correctly-signed envelope at `/sales`, the visitor
+refuses it — the signature is real, but the signed address says `/support` and the visitor
+dialled `/sales`. That is what lets two agents share a hostname safely.
+
+Routing a fleet with nginx — pass the prefix **through** (no trailing slash on `proxy_pass`)
+so each entry sees the path its card claims:
+
+```nginx
+location /support/ { proxy_pass http://127.0.0.1:8788; }
+location = /support { proxy_pass http://127.0.0.1:8788; }
+location /sales/   { proxy_pass http://127.0.0.1:8789; }
+location = /sales  { proxy_pass http://127.0.0.1:8789; }
+```
+
+If your proxy **strips** the prefix instead (`proxy_pass http://127.0.0.1:8788/` — note the
+trailing slash), pass `basePath: ''`. That is the one override, and it may only be `''` or
+exactly the path `baseUrl` already names; anything else refuses at startup, because a third
+spelling of your address is the thing this design exists to prevent.
+
+Inside one Express app, use `req.originalUrl` — never `req.url`, which a mounted router has
+already stripped:
+
+```js
+const fwd = (entry) => async (req, res) => {
+  const r = await entry.handleRequestAsync(req.method, req.originalUrl, req.headers, req.body);
+  res.status(r.status).set(r.headers).send(r.body);
+};
+```
+
+## Which domains this entry speaks for
+
+An entry can name the domains it belongs to:
+
+```js
+createAgentEntry({ seedHex, baseUrl: 'https://studio.example',
+                   domains: ['studio.example'], responder });
+```
+
+This is **one half of a two-sided proof**, and it is worth being clear about what each half
+does. Your card says "I speak for studio.example". The domain says, in a
+`/.well-known/did-configuration.json` it serves, "this DID speaks for me". A verifier accepts
+the binding only when **both** halves agree — so neither a domain that lists a DID it does
+not own, nor an agent that claims a domain it has never touched, proves anything alone. And
+either side can withdraw: the domain owner deletes one line from a file they already control,
+and that agent — and only that agent — stops verifying.
+
+That is why a domain may name many agents. Revoking one is a one-line edit, not a migration.
+
+Names are checked at startup: a bare host, at least two labels, ASCII only, an optional
+`:port`, at most five of them. Anything else — a scheme, a path, a stray space, an empty
+entry from a trailing comma — **refuses to start**. So does naming more than five, rather
+than quietly publishing the first five: a claim that is usable and is not what you said is
+worse than a refusal you can read.
+
+Naming no domain is the default and publishes exactly what 1.1.x did.
+
+Set it from the environment with `AGENT_ENTRY_DOMAINS=studio.example,support.studio.example`.
+
 ## Pairs with WebMCP: the tab conversation becomes a customer
 
 If your page already exposes [WebMCP](https://github.com/MiguelsPizza/WebMCP) tools, you have
@@ -205,18 +323,62 @@ the source:
   seconds; if your site needs that speed, put the check in the backend your `responder`
   calls.
 
+What the entry now handles for you at the HTTP layer, so you do not have to:
+
+- **A stranger always gets an HTTP response.** Never a silently closed socket, whatever they
+  send. A request that stalls gets `408`; past a connection ceiling a new one gets `503`.
+- **Slow-drip connections cannot pile up.** Headers, body and idle keep-alives each have a
+  wall-clock bound. A socket timeout alone does not stop this: a caller sending one byte per
+  interval resets it forever, and the read only ends when it has everything it asked for.
+- **Ambiguous framing is refused, not guessed.** A repeated `Content-Length`, a
+  `Content-Length` alongside `Transfer-Encoding`, or a length that is not plain digits is a
+  `400`. Those are the shapes that make a proxy and an origin disagree about where one
+  request ends and the next begins. Chunked bodies on their own are accepted and decoded,
+  bounded by the same limits, because a reverse proxy may legitimately re-frame a request.
+- **The body must be real UTF-8.** Invalid bytes are refused rather than silently replaced,
+  so the two implementations cannot disagree about what you were sent.
+- **The request target must be in origin form.** `POST /` — not
+  `POST https://elsewhere.example/`. This is a deliberate departure from RFC 9112 §3.2.2,
+  which says a server must accept the absolute form: this endpoint answers exactly the
+  address its card names, and the refusal says so.
+
 ## Two implementations, pinned to each other
 
-`examples/reference.py` is the Python reference. It is not a port — the two are held
-byte-identical by an acceptance suite that runs the same attack battery against both,
-drives this module against `testdata/wire_vectors.json`, posts identical bytes to each,
-and requires identical verdicts. If you write a third implementation, that suite is the
-gate.
+This module is not alone. A Python reference implements the same contract, and the two are
+held to **identical verdicts** by an acceptance suite: it runs the same attack battery
+against both, drives this module against `testdata/wire_vectors.json` byte for byte, posts
+identical bytes to each over real sockets — down to the HTTP framing — and requires the same
+status, the same account outcome and the same signed reply from both. If you write a third
+implementation, that suite is the gate.
 
 The bytes are the contract: every signed payload must match Python's canonical JSON
 exactly, or a signature is unverifiable and the only diagnostic anyone gets is
 "signature verification failed".
 
+**What ships here, and what does not.** This repo is the **site side**: the door a website runs.
+It is one file, it depends on nothing, and it carries everything it needs including its own
+Ed25519.
+
+The other implementation is a Python one, and it lives with Muretai core, where it is the
+executable specification the acceptance suite drives. It is not published here on purpose. A
+door needs a signer, a card, a binding verifier and a domain-name check; core's copy reaches
+for a URL guard, a JWS minter and a release module that a door never touches, and shipping
+those here would put the *visiting-agent* and *node* sides of the network into an artifact that
+is only ever the site side.
+
+The visiting side needs nothing from this package either: an agent already has a runtime — a
+Muretai node, or whatever framework it runs on — and that is what knocks on your door.
+
+So the two implementations share no code at all, by design. **What holds them to identical
+verdicts is the acceptance suite, not a shared library** — which is the honest arrangement,
+because a shared library would only ever have covered the parts they happen to share. The
+suite posts identical bytes to both, down to the HTTP framing, and requires the same status,
+the same account outcome and the same signed reply.
+
+`testdata/wire_vectors.json` is the part of that gate you can run here: it pins the canonical
+JSON, the signing payloads, the card envelopes and the did:key round-trips this module must
+reproduce byte for byte.
+
 ## What this is part of
 
 [Muretai](https://muretai.com) is a network where AI agents that belong to *different
@@ -227,4 +389,13 @@ that has to stay awake.
 You do not need the rest of the network to use this file. It is useful on its own the
 moment an agent knocks.
 
+## Questions
+
+Ask — there is no wrong question about this, and the answers usually improve the docs.
+
+- **X:** [@muretaiai](https://x.com/muretaiai) — mention us, we read them
+- **Issues:** [github.com/muretai/agent-entry/issues](https://github.com/muretai/agent-entry/issues)
+- **Security:** please report privately first, at
+  [muretai.com/.well-known/security.txt](https://muretai.com/.well-known/security.txt)
+
 MIT.

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
- * `muretai-agent-entry.mjs` to a demo booking desk. Copy it, gut the responder,
+ * `web/agent-entry/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:
@@ -20,18 +20,43 @@
  *                       into the Agent Card and a visitor requires the card to name the
  *                       origin it dialled — behind a proxy or a tunnel, set this to the
  *                       public URL or every verification fails. Default http://127.0.0.1:<port>.
+ *                       It MAY include a path (https://example.com/support): the entry then
+ *                       answers THERE and 404s the bare host, so one hostname can hold
+ *                       several agents — a front desk, support, sales — each its own key.
+ *   AGENT_ENTRY_DOMAINS    comma-separated bare domains this entry speaks for, e.g.
+ *                       "example.com". Half a proof: the domain must ALSO serve a
+ *                       credential naming this DID at /.well-known/did-configuration.json,
+ *                       or a verifier correctly reports the agent withdrew its side.
+ *                       At most 5, and every segment must be a bare domain — a doubled or
+ *                       trailing comma REFUSES to start rather than quietly publishing
+ *                       one name fewer than you wrote.
  *   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)
  */
 
-import { createAgentEntry, newSeedHex, didFromSeedHex, AGENT_CARD_PATH }
+import { createAgentEntry, newSeedHex, didFromSeedHex, trimOuter, AGENT_CARD_PATH }
   from '../muretai-agent-entry.mjs';
 
 const port = Number(process.env.AGENT_ENTRY_PORT || 8788);
 const host = process.env.AGENT_ENTRY_HOST || '127.0.0.1';
 const baseUrl = process.env.AGENT_ENTRY_BASE_URL || `http://127.0.0.1:${port}`;
 const name = process.env.AGENT_ENTRY_NAME || 'Example Studio';
+// An absent (or blank) variable means NO domains at all, and the card then carries no
+// `domains` key. Anything else is split on ',' and every segment is handed on AS WRITTEN:
+// an EMPTY segment (`a,,b`, or a trailing comma) is REFUSED by createAgentEntry, never
+// skipped. A name lost in an edit looks exactly like a harmless typo, and starting with
+// fewer domains than the operator named is the same silent mismatch `canonicalBaseUrl`
+// refuses one field over. Must match the split rule in examples/agent_entry_reference.py.
+//
+// "Blank" is `trimOuter` — the intersection `canonicalDomains` folds with — and NOT
+// `trim()`, which is where the two runners drifted apart: `trim()` also removes U+FEFF and
+// Python's `strip()` also removes \x1c-\x1f and U+0085, so the SAME variable got two
+// verdicts. Measured: `AGENT_ENTRY_DOMAINS="\x1c"` started the Python runner with no
+// domains and made this one exit 2; a BOM — what a paste out of a spreadsheet or a Windows
+// .env carries — did exactly the reverse. One fold, one verdict.
+const rawDomains = process.env.AGENT_ENTRY_DOMAINS || '';
+const domains = trimOuter(rawDomains) ? rawDomains.split(',') : [];
 
 let seedHex = process.env.AGENT_ENTRY_SEED_HEX;
 if (!seedHex) {
@@ -47,7 +72,7 @@ if (!seedHex) {
  *  both. In production: POST `env` to your app behind a bearer token and return its answer
  *  (a string, or {text}). It may be async. Treat `env.text` as untrusted DATA. */
 function responder(env) {
-  // Say out loud what just happened. A agent entry's whole claim is "the first signed message IS
+  // Say out loud what just happened. An agent entry's whole claim is "the first signed message IS
   // 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.
@@ -76,21 +101,37 @@ function responder(env) {
     + 'tell you what is open.';
 }
 
-const entry = createAgentEntry({
-  seedHex,
-  name,
-  baseUrl,
-  description: 'Books photo shoots. Send a signed message; you get a signed answer.',
-  responder,
-  openDoor: true,                                     // "you may contact me, no introduction"
-  anonymousLane: process.env.AGENT_ENTRY_ANON === '1',
-});
+// A bad AGENT_ENTRY_BASE_URL or AGENT_ENTRY_DOMAINS throws HERE, before the socket is
+// bound: the entry never starts and never publishes a claim no visitor could use. The
+// message names the value and what to paste instead, so print it plainly — a stack trace
+// tells a site operator nothing.
+let entry;
+try {
+  entry = createAgentEntry({
+    seedHex,
+    name,
+    baseUrl,
+    domains,
+    description: 'Books photo shoots. Send a signed message; you get a signed answer.',
+    responder,
+    openDoor: true,                                     // "you may contact me, no introduction"
+    anonymousLane: process.env.AGENT_ENTRY_ANON === '1',
+  });
+} catch (err) {
+  console.error(err && err.message ? err.message : String(err));
+  process.exit(2);
+}
 
 const server = entry.listen(port, host, () => {
-  console.log(`${name} is agent-reachable on ${baseUrl}`);
+  console.log(`${name} is agent-reachable on ${entry.card.url}`);
   console.log(`  DID:  ${entry.did}`);
-  console.log(`  Card: ${baseUrl.replace(/\/+$/, '')}${AGENT_CARD_PATH}`);
-  console.log(`  Listening on ${host}:${port} — POST a signed message/send to /`);
+  console.log(`  Card: ${entry.card.url}${AGENT_CARD_PATH}`);
+  if (entry.card.domains) {
+    console.log(`  Speaking for: ${entry.card.domains.join(', ')} — each domain must serve a `
+      + 'credential naming this DID at /.well-known/did-configuration.json');
+  }
+  console.log(`  Listening on ${host}:${port} — POST a signed message/send to `
+    + `${entry.mount || '/'}`);
 });
 
 // A port collision is the first thing anyone running this twice hits (a previous run that was

package/muretai-agent-entry.mjs

@@ -54,6 +54,12 @@ export const CARD_SIG_REFRESH_S = 3600;
  *  wrote. Must match `ANON_RATE_PER_MIN` in examples/agent_entry_reference.py: one contract,
  *  two implementations, one bound. */
 export const ANON_RATE_PER_MIN = 30;
+/** How many domains one card may advertise (agent/domainstore.MAX_CARD_DOMAINS, and the
+ *  same ceiling shared/protocol.build_agent_card applies to a node's card). Every name
+ *  listed is an outbound HTTPS fetch this entry asks strangers to make, so the cap bounds
+ *  the work an entry can push onto its visitors — not how many domains a site may own.
+ *  Must match `MAX_CARD_DOMAINS` in examples/agent_entry_reference.py. */
+export const MAX_CARD_DOMAINS = 5;
 
 export const AGENT_CARD_PATH = '/.well-known/agent-card.json';
 export const AGENT_CARD_PATH_LEGACY = '/.well-known/agent.json';
@@ -796,6 +802,20 @@ class RateBound {
   }
 }
 
+/**
+ * An unpaired UTF-16 surrogate — a string with no UTF-8 encoding at all.
+ *
+ * `"\ud800"` is legal JSON and both parsers accept it, but Python's `.encode("utf-8")`
+ * RAISES on it while a JavaScript Buffer quietly substitutes U+FFFD. Measured: a one-shot
+ * POST carrying `"text": "\ud800"` from a stranger with no key killed the Python reference
+ * entry's request with no HTTP response, and was answered -32001 here — same bytes, two
+ * verdicts, one of them a dead socket. It is not text; the shape gate refuses it on both.
+ *
+ * Written without the `u` flag on purpose: in a Unicode-mode pattern these ranges are not
+ * matchable as isolated code units, which is exactly what has to be matched here.
+ */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
 /**
  * The STRICT type check on the fields that end up inside the signed payload. Returns a
  * reason string, or null when the shape is acceptable.
@@ -809,6 +829,16 @@ class RateBound {
  * JavaScript renders it `1` and Python renders it `1.0`, so exactly one of them can verify
  * the signature — and we would then ECHO it into our own signed reply.
  *
+ * Also here, and for the same reason, are the ENVELOPE fields — `metadata` and the
+ * `from`/`to`/`sig` inside it. Step 4 below can only ask "is it there", and a wrongly-typed
+ * one answered that question WRONG on both twins in opposite directions: `metadata: "x"`
+ * read as an EMPTY envelope here (so -32001, or — with the anonymous lane on — a SIGNED
+ * ANONYMOUS REPLY, a malformed envelope silently downgraded to a walk-in) while the Python
+ * reference answered -32600; and `metadata.to = 1` survived Python's presence test and
+ * reached `to_did[:24]`, a TypeError that closed the socket with no HTTP response at all.
+ * A partial or malformed envelope is never an absent one — that rule is already written
+ * down for a stripped `sig` in docs/AGENT_ENTRY.md, and it holds for the type too.
+ *
  * -32600 (Invalid Request) for all of them: a wrongly-typed field is a malformed request,
  * not a failed signature. `examples/agent_entry_reference.py::_wire_shape_error` answers the
  * same code for the same input, case for case.
@@ -825,14 +855,49 @@ function wireShapeError(msg) {
     if ('text' in part && typeof part.text !== 'string') {
       return 'a text part\'s `text` must be a string';
     }
+    if (typeof part.text === 'string' && LONE_SURROGATE.test(part.text)) {
+      return 'a text part\'s `text` is not encodable UTF-8 (a lone surrogate)';
+    }
   }
   if (typeof msg.messageId !== 'string' || !msg.messageId) {
     return 'messageId must be a non-empty string';
   }
+  if (LONE_SURROGATE.test(msg.messageId)) {
+    return 'messageId is not encodable UTF-8 (a lone surrogate)';
+  }
   if (msg.contextId !== undefined && msg.contextId !== null
       && typeof msg.contextId !== 'string') {
     return 'contextId must be a string or null';
   }
+  if (typeof msg.contextId === 'string' && LONE_SURROGATE.test(msg.contextId)) {
+    return 'contextId is not encodable UTF-8 (a lone surrogate)';
+  }
+  // The ENVELOPE fields. `null` reads as ABSENT (the stripped-sig case the ladder answers
+  // -32001 for, and the shape of a walk-in on the anonymous lane); PRESENT-but-not-a-string
+  // is a malformed request and is never an absent envelope. `typeof null === 'object'` and
+  // an Array is an object too, so both are excluded explicitly.
+  const meta = msg.metadata;
+  if (meta !== undefined && meta !== null
+      && (typeof meta !== 'object' || Array.isArray(meta))) {
+    return 'metadata must be an object';
+  }
+  for (const field of ['from', 'to', 'sig']) {
+    const v = (meta ?? {})[field];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'string') return `metadata.${field} must be a string`;
+    if (LONE_SURROGATE.test(v)) {
+      return `metadata.${field} is not encodable UTF-8 (a lone surrogate)`;
+    }
+  }
+  // LAST, because the Python reference reaches the equivalent refusal last: its shape gate
+  // runs and THEN `Message.from_a2a` raises. `kind: "message"` is what makes this an A2A
+  // Message rather than some other object that happens to carry a `parts` array, and
+  // `shared/protocol.py::from_a2a` has always required it — while this file had no check at
+  // all. Measured with a valid signature and a fresh timestamp: a message with `kind`
+  // removed was ACCEPTED here, BOOKED AN ACCOUNT and got a signed reply, where the reference
+  // answered -32600. A muretai NODE refuses the same bytes, so accepting them would also
+  // mean the entry tier and the node tier disagree about what an A2A message is.
+  if (msg.kind !== 'message') return 'not an A2A message object';
   return null;
 }
 
@@ -846,6 +911,61 @@ const CORS_HEADERS = {
   'Access-Control-Max-Age': '600',
 };
 
+/** The refusal text for a request-target that is not in origin form. Shared with
+ *  `ORIGIN_FORM_ONLY` in examples/agent_entry_reference.py so the two twins return the same
+ *  diagnostic for the same request. */
+const ORIGIN_FORM_ONLY = 'the request-target must be an origin-form path: this entry answers '
+  + 'exactly the address its card names, and that address has no other spelling';
+
+/** Transport bounds. Node bounds the first three by DEFAULT (300 s / 60 s / 5 s) and the
+ *  Python reference bounded NONE, which made it the only tier a stranger could wedge with no
+ *  key and no request body — 40 trickle connections took it from 2 threads to 42 with 0
+ *  responses. These are the numbers BOTH twins now use, spelled here so the two files can be
+ *  read against each other: `AgentEntry.HEADER_TIMEOUT` / `BODY_BUDGET` /
+ *  `KEEPALIVE_TIMEOUT` / `MAX_CONNECTIONS`. */
+const HEADERS_TIMEOUT_MS = 20_000;
+const REQUEST_TIMEOUT_MS = 20_000;
+const KEEPALIVE_TIMEOUT_MS = 5_000;
+const MAX_CONNECTIONS = 64;
+
+/** What the (MAX_CONNECTIONS+1)-th connection is answered with, byte for byte the same
+ *  response `_BoundedThreadingHTTPServer` writes in the Python reference. */
+const OVERLOADED_BODY = '{"error":"too many concurrent connections"}';
+const OVERLOADED_RESPONSE = 'HTTP/1.1 503 Service Unavailable\r\n'
+  + 'Content-Type: application/json; charset=utf-8\r\n'
+  + `Content-Length: ${OVERLOADED_BODY.length}\r\n`
+  + 'Connection: close\r\n\r\n' + OVERLOADED_BODY;
+
+/** The stdlib's STRICT UTF-8 decoder: it THROWS on an invalid byte instead of substituting
+ *  U+FFFD, which is what `Buffer.toString('utf8')` does and what let a body neither
+ *  implementation could agree about reach the ladder. Node global since v11 — no dependency. */
+const STRICT_UTF8 = new TextDecoder('utf-8', { fatal: true });
+
+/**
+ * The JSON-RPC `id` we may ECHO, or null.
+ *
+ * JSON-RPC 2.0 says an id is a String, a Number or Null — never an object or an array — and
+ * this enforces exactly that, for a reason larger than pedantry: the id is the ONE field no
+ * signature covers and it is written straight back out, so whatever the two runtimes
+ * disagree about here becomes a disagreement about the whole response. Two measured cases,
+ * both closed by refusing the SHAPE rather than the instance:
+ *   - `id = {"x":"\ud800"}`. `JSON.stringify` escapes the lone surrogate happily; Python's
+ *     `p.dumps` RAISES, so the reference booked the account and then died in serialisation
+ *     (HTTP 500, no reply, customer on the books) while this file answered 200 and signed.
+ *   - a number outside ±2^53. `10**400` arrives here as `Infinity` and re-serialises as
+ *     `null`, while Python echoes the bigint verbatim.
+ * `null` is what JSON-RPC allows for an unusable id, and it keeps the VERDICT — not the
+ * echo — as the thing the two implementations have to agree on.
+ * Mirrors `AgentEntry._safe_id` in examples/agent_entry_reference.py.
+ */
+function safeId(id) {
+  if (typeof id === 'string') return LONE_SURROGATE.test(id) ? null : id;
+  if (typeof id === 'number') {
+    return (Number.isFinite(id) && Math.abs(id) <= 2 ** 53) ? id : null;
+  }
+  return null;
+}
+
 function jsonResponse(status, obj, extraHeaders = {}) {
   const body = Buffer.from(JSON.stringify(obj), 'utf8');
   return {
@@ -870,6 +990,475 @@ function isThenable(v) {
   return v !== null && typeof v === 'object' && typeof v.then === 'function';
 }
 
+// ---------------------------------------------------------------- baseUrl canonicalisation
+
+/** RFC 3986 `pchar` plus '/' — the only characters an accepted path may carry. Everything
+ *  outside this set is percent-encoded by `new URL()` and left verbatim by Python's
+ *  urlsplit, which is precisely the divergence canonicalBaseUrl exists to prevent. */
+const PATH_OK = new Set(
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~!$&'()*+,;=:@/");
+const HEX = new Set('0123456789abcdefABCDEF');
+/** A host is lowercased before this is applied. '_' is not legal in a hostname but is real
+ *  in the wild and both parsers keep it verbatim, so it is not a divergence. */
+const HOST_OK = new Set('abcdefghijklmnopqrstuvwxyz0123456789.-_');
+const DEFAULT_PORT = { http: 80, https: 443 };
+
+/**
+ * `'.'` or `'..'` if this path segment is a dot segment AS THE URL PARSERS SEE IT, else null.
+ *
+ * Raw `.` and `..` are the obvious spellings; `new URL()` ALSO removes `%2e`, `%2E` and every
+ * mixture (`.%2e`, `%2e.`, `%2e%2e`), and Python's `urlsplit` removes none of them. A segment
+ * test written against the raw text therefore lets exactly that family through: measured,
+ * `https://shop.example/a/%2e%2e/support` started and published on the Python side, and was
+ * refused here only by the `new URL()` tripwire at the bottom of canonicalBaseUrl — which
+ * announced "a bug in this file, not in your input" for an input problem with a paste-able
+ * fix. Decoding just this one escape (never the whole segment — `%41` must stay `%41`, it is
+ * a different path) makes both implementations refuse the same family, for the right reason.
+ */
+function dotSegment(seg) {
+  const decoded = seg.replaceAll('%2e', '.').replaceAll('%2E', '.');
+  return (decoded === '.' || decoded === '..') ? decoded : null;
+}
+
+/** Raise the one refusal shape, in the order an operator can act on at 2am: what they gave
+ *  (JSON-quoted, so an invisible tab is VISIBLE), which rule in words, the fix as a string
+ *  they can paste, and one clause of why. `<field> is not publishable:` is the greppable
+ *  stem the Python twin shares — `base_url` for the address, `domains` for the names this
+ *  entry claims to speak for, `base_path` for the mount override. */
+function refuseBaseUrl(given, rule, why, fix, field = 'base_url') {
+  const lines = [`${field} is not publishable: ${rule}`, `  given: ${JSON.stringify(given)}`];
+  if (fix) lines.push(`  use:   ${JSON.stringify(fix)}`);
+  lines.push(`  ${why}`);
+  throw new TypeError(lines.join('\n'));
+}
+
+/**
+ * canonicalBaseUrl(baseUrl) -> the exact string this entry may publish as its card `url`.
+ *
+ * The contract, and the only reason this function exists: **the returned value equals what
+ * a VISITOR computes** from the url they dialled (`Outbox.card_scope` in agent/outbox.py)
+ * when deciding whether this card is about this site. An entry that publishes anything else
+ * fails verification on a stranger's machine, with "signature verification failed" as the
+ * only diagnostic and nothing at all on the operator's screen.
+ *
+ * So every input on which the operator's spelling and the visitor's arithmetic could
+ * disagree — or on which this file and its Python twin (examples/agent_entry_reference.py)
+ * could disagree — is REFUSED here, loudly, at construction. The two are held byte-identical
+ * by an acceptance suite; a value they canonicalise differently is a signed-bytes split for
+ * identical operator input, which is the bug this whole function is about.
+ *
+ * It HAND-PARSES rather than using `new URL()`, which is not a candidate: it keeps a trailing
+ * DNS dot (`https://x.`) that the verifier drops, punycodes hosts, percent-encodes non-ASCII,
+ * spaces and `|^{}`, removes dot segments, and rewrites `\` to `/` — five spellings Python
+ * does not produce. `new URL()` runs at the END instead, as a tripwire: if a future Node
+ * changes the parser out from under the hand-parse, that is a loud startup failure here
+ * rather than silent byte drift discovered by a customer whose card stopped verifying.
+ *
+ * The gate (steps 1-7) runs before any folding, which is what makes the folds safe: it
+ * removes exactly the inputs the two languages disagree about, so every remaining fold is
+ * one they already agree on.
+ */
+export function canonicalBaseUrl(baseUrl, { warn = true } = {}) {
+  if (typeof baseUrl !== 'string' || !baseUrl.trim()) {
+    refuseBaseUrl(baseUrl, 'it is empty.', undefined,
+      'Set it to the URL visitors actually dial — it is what your signed card claims, and '
+      + 'a card naming a different origin proves nothing about yours.');
+  }
+  const s = baseUrl.trim();
+
+  for (const ch of s) {
+    const c = ch.codePointAt(0);
+    if (c >= 0x21 && c <= 0x7e) continue;
+    if (c > 0x7e) {
+      const hostGuess = (s.split('://')[1] ?? s).split('/')[0];
+      let fix;
+      try {                                     // best-effort A-label, for the message only
+        const asciiHost = new URL(`https://${hostGuess}`).hostname;
+        if (asciiHost && asciiHost !== hostGuess) fix = s.replace(hostGuess, asciiHost);
+      } catch { /* not a host we can suggest a spelling for */ }
+      refuseBaseUrl(s, 'it is not ASCII.', fix,
+        'Python and JavaScript disagree on how to spell this (Python keeps it as typed, '
+        + 'JavaScript percent-encodes or punycodes it), so the two Agent Entry '
+        + 'implementations would sign different bytes for the same site. Supply the ASCII '
+        + 'form, and publish your links and QR codes in that same form.');
+    }
+    refuseBaseUrl(s, 'it contains whitespace or a control character.', undefined,
+      'Both URL parsers DELETE a tab or newline silently and mid-string, so the value you '
+      + 'meant and the value that gets signed are not the same string and nothing tells you.');
+  }
+
+  if (s.includes('\\')) {
+    refuseBaseUrl(s, 'it contains a backslash.', s.replaceAll('\\', '/'),
+      "JavaScript reads '\\' as '/' and Python does not, so the two Agent Entry "
+      + 'implementations would disagree about where the host ends.');
+  }
+  for (const [bad, label] of [['?', 'a query string'], ['#', 'a fragment']]) {
+    if (s.includes(bad)) {
+      refuseBaseUrl(s, `it carries ${label}.`, s.split(bad)[0] || undefined,
+        'This string is signed into your Agent Card, and every visitor compares it to the '
+        + 'URL they dialled — which never carries one.');
+    }
+  }
+
+  const sep = s.indexOf('://');
+  const scheme = sep < 0 ? '' : s.slice(0, sep).toLowerCase();
+  if (sep < 0 || !(scheme in DEFAULT_PORT)) {
+    refuseBaseUrl(s, 'it is not an http(s) URL.',
+      sep < 0 && !s.startsWith('/') ? `https://${s}` : undefined,
+      'An Agent Card names an origin a visitor can dial over HTTP.');
+  }
+  const rest = s.slice(sep + 3);
+  const cut = rest.indexOf('/');
+  const authority = cut < 0 ? rest : rest.slice(0, cut);
+  let path = cut < 0 ? '' : rest.slice(cut);
+
+  if (authority.includes('@')) {
+    refuseBaseUrl(s, "it carries userinfo (a '@' before the host).",
+      `${scheme}://${authority.slice(authority.lastIndexOf('@') + 1)}${path}`,
+      "The part before '@' is not the host: a visitor dials the part AFTER it, so a card "
+      + 'built from this string would name a different site than the one being served.');
+  }
+  if (authority.includes('%')) {
+    refuseBaseUrl(s, 'the host contains a percent-escape.', undefined,
+      'Python lowercases it into the host and JavaScript refuses the URL outright, so the '
+      + 'two Agent Entry implementations cannot agree.');
+  }
+
+  let host;
+  let portS;
+  if (authority.startsWith('[')) {              // IPv6 literal — brackets are part of it
+    const close = authority.indexOf(']');
+    if (close < 0) {
+      refuseBaseUrl(s, "the IPv6 host is missing its closing ']'.", undefined,
+        'An address literal must be bracketed, e.g. http://[::1]:9000');
+    }
+    host = authority.slice(0, close + 1).toLowerCase();
+    const tail = authority.slice(close + 1);
+    if (tail && !tail.startsWith(':')) {
+      refuseBaseUrl(s, 'there is text after the IPv6 address.', undefined,
+        "Only ':<port>' may follow a bracketed address.");
+    }
+    portS = tail ? tail.slice(1) : '';
+  } else {
+    const colon = authority.lastIndexOf(':');
+    host = (colon < 0 ? authority : authority.slice(0, colon)).toLowerCase();
+    portS = colon < 0 ? '' : authority.slice(colon + 1);
+  }
+
+  let port = null;
+  if (portS) {
+    const n = Number(portS);
+    if (!/^[0-9]+$/.test(portS) || !Number.isInteger(n) || n < 1 || n > 65535) {
+      refuseBaseUrl(s, `the port ${JSON.stringify(portS)} is not a number in 1-65535.`,
+        undefined, 'A visitor dials a real port; anything else cannot be reached.');
+    }
+    port = n;
+  }
+  host = host.replace(/\.+$/, '');              // trailing dot: DNS-equal, byte-different
+  if (!host || (!host.startsWith('[') && [...host].some((c) => !HOST_OK.has(c)))) {
+    refuseBaseUrl(s, 'the host is missing or contains characters that are not a hostname.',
+      undefined, 'A card must name a host a visitor can resolve.');
+  }
+
+  path = path.replace(/\/+$/, '');              // ALL of them: card_scope uses rstrip too
+  if (path) {
+    for (let i = 0; i < path.length;) {
+      const ch = path[i];
+      if (ch === '%') {
+        if (path.length - i < 3 || !HEX.has(path[i + 1]) || !HEX.has(path[i + 2])) {
+          refuseBaseUrl(s, 'the path has a malformed percent-escape.', undefined,
+            "'%' must be followed by exactly two hex digits, or the two URL parsers "
+            + 'disagree about what the path is.');
+        }
+        i += 3;
+        continue;
+      }
+      if (!PATH_OK.has(ch)) {
+        refuseBaseUrl(s, `the path contains ${JSON.stringify(ch)}, which is not allowed `
+          + 'unencoded.', undefined,
+        'JavaScript percent-encodes this character and Python leaves it verbatim, so the '
+        + 'two Agent Entry implementations would sign different bytes. Percent-encode it '
+        + 'yourself.');
+      }
+      i += 1;
+    }
+    const parts = path.split('/');
+    if (parts.some((seg) => dotSegment(seg) !== null)) {
+      const segs = [];                          // RFC 3986 remove_dot_segments, for the fix
+      for (const seg of parts) {
+        const dot = dotSegment(seg);
+        if (dot === '.') continue;
+        if (dot === '..') { if (segs.length > 1) segs.pop(); continue; }
+        segs.push(seg);
+      }
+      refuseBaseUrl(s, "the path contains '.' or '..' segments "
+        + "(the percent-encoded spellings '%2e' and '%2E' count).",
+      `${scheme}://${authority}${segs.join('/').replace(/\/+$/, '')}`,
+      'JavaScript collapses these segments — encoded ones included — and Python does not, '
+      + 'so the two Agent Entry implementations would sign different bytes.');
+    }
+  }
+
+  const originOut = `${scheme}://${host}${port !== null && port !== DEFAULT_PORT[scheme] ? `:${port}` : ''}`;
+  const out = originOut + path;
+
+  // The tripwire. Not redundant with the hand-parse: it is what turns a future Node/WHATWG
+  // change into a loud startup failure instead of silent byte drift. If this ever fires,
+  // the hand-parse and the platform parser have diverged on an input the gate let through.
+  //
+  // It must NOT claim to know which of the two is at fault. It used to open with "a bug in
+  // this file, not in your input" and send the operator to an issue tracker — and the input
+  // that actually fired it was `https://shop.example/a/%2e%2e/support`, an encoded dot
+  // segment, which is an input problem with a paste-able fix (now refused above, by name).
+  // A tripwire sees a disagreement, not a culprit. Name both, input first.
+  const probe = new URL(out);
+  if (probe.origin !== originOut || probe.pathname !== (path || '/')
+      || probe.search || probe.hash) {
+    throw new TypeError(
+      `base_url is not publishable: canonicalising it produces a value this runtime's URL `
+      + `parser reads differently.\n`
+      + `  given: ${JSON.stringify(baseUrl)}\n`
+      + `  this file canonicalises it to ${JSON.stringify(out)}, which the URL parser reads `
+      + `as ${JSON.stringify(probe.origin + probe.pathname)}.\n`
+      + `  Check the address first — a spelling this gate does not know how to fold lands `
+      + `here. If it is an ordinary http(s) URL with no unusual escaping, this is a bug in `
+      + `this file: please report it at https://github.com/muretai/agent-entry/issues`);
+  }
+
+  if (warn) {
+    if (/[A-Z]/.test(path)) {
+      process.stderr.write(`warning: base_url path ${JSON.stringify(path)} contains `
+        + `uppercase letters. Paths are case-SENSITIVE and are not folded by the visitor's `
+        + `check, so a visitor who dials ${JSON.stringify(path.toLowerCase())} will fail to `
+        + `verify your card. Make sure every link, invite and QR code you publish spells it `
+        + `exactly ${JSON.stringify(path)}.\n`);
+    }
+    if (path.includes('%')) {
+      process.stderr.write(`warning: base_url path ${JSON.stringify(path)} contains a `
+        + `percent-escape. It is compared verbatim, case included, so a visitor who dials `
+        + `another spelling of the same path will fail to verify your card.\n`);
+    }
+    if (scheme === 'http' && !['localhost', '127.0.0.1', '[::1]'].includes(host)) {
+      process.stderr.write(`warning: base_url ${JSON.stringify(out)} is plain HTTP on a `
+        + `public host. A visiting agent refuses a plain-http open door (the message text `
+        + `would cross the wire in the clear), so this entry will be skipped by every `
+        + `well-behaved visitor. Use https.\n`);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------- domains + the mount
+
+/** The outer whitespace BOTH languages strip identically. Python's `str.strip()` also
+ *  removes \x1c-\x1f, U+0085 and U+00A0; JavaScript's `trim()` removes a different tail of
+ *  Unicode spaces. Folding only this intersection — and refusing every other character
+ *  outside 0x21..0x7E — is what stops the twins accepting different strings for the same
+ *  operator input. Must match `_OUTER_WS` in examples/agent_entry_reference.py. */
+const OUTER_WS = ' \t\n\r\f\v';
+/** Characters that betray a URL, an authority or whitespace smuggling where a bare domain
+ *  was expected (shared/domainbind._NOT_IN_DOMAIN). */
+const NOT_IN_DOMAIN = ['/', '?', '#', '@', '\\', ' ', '\t', '\r', '\n', '%', '[', ']'];
+const LDH = new Set('abcdefghijklmnopqrstuvwxyz0123456789-');
+/** RFC 1035 total length of a domain name, applied to the HOST only, plus the longest
+ *  legal ":<port>" for the raw-input bound (shared/domainbind.MAX_DOMAIN_LEN). */
+const MAX_DOMAIN_LEN = 253;
+
+/** Exported because the RUNNER needs the same fold: `examples/agent_entry_server.mjs` decides
+ *  whether `AGENT_ENTRY_DOMAINS` is blank at all, and it used `trim()`. That is a different
+ *  set from Python's `strip()` in BOTH directions, so one variable got two verdicts — a
+ *  `\x1c` started the Python runner with no domains and made this one exit 2, and a BOM
+ *  (what a paste out of a spreadsheet or a Windows `.env` carries) did the reverse. */
+export function trimOuter(s) {
+  let a = 0;
+  let b = s.length;
+  while (a < b && OUTER_WS.includes(s[a])) a += 1;
+  while (b > a && OUTER_WS.includes(s[b - 1])) b -= 1;
+  return s.slice(a, b);
+}
+
+/**
+ * The JS twin of `shared/domainbind.valid_domain` — the ONE definition of "is this a bare
+ * domain" in this system, and therefore the one both halves of a domain binding must agree
+ * on. Total on untrusted input; never throws.
+ *
+ * A domain here is not a URL: ASCII LDH labels only (a-z, 0-9, '-'), LOWERCASE (case is
+ * folded by the caller, visibly, because `valid_domain` REJECTS an uppercase spelling
+ * rather than folding it), 1..63 characters per label, no leading or trailing '-', at
+ * least two labels (a single-label name has no owner a verifier could hold responsible),
+ * host <= 253 with no trailing dot, and an optional ':<port>' 1..65535 with no leading
+ * zero. Ports exist only because a loopback or staging box cannot use 443.
+ *
+ * Re-implemented rather than imported for the same reason everything else in this file is:
+ * a site copies ONE file. `test_agent_entry_contract.py` is what holds the two spellings to
+ * the same verdicts.
+ */
+function validBareDomain(domain) {
+  if (typeof domain !== 'string' || !domain || domain.length > MAX_DOMAIN_LEN + 6) {
+    return false;
+  }
+  if (NOT_IN_DOMAIN.some((ch) => domain.includes(ch))) return false;
+  for (const ch of domain) if (ch.codePointAt(0) > 0x7f) return false;   // IDN U-labels
+  let host = domain;
+  const colon = domain.indexOf(':');            // the FIRST one: `str.partition` semantics
+  if (colon >= 0) {
+    host = domain.slice(0, colon);
+    const portS = domain.slice(colon + 1);      // a second ':' leaves a non-numeric tail
+    if (!/^[0-9]+$/.test(portS)) return false;
+    if (portS.length > 1 && portS.startsWith('0')) return false;
+    const port = Number(portS);
+    if (port < 1 || port > 65535) return false;
+  }
+  if (!host || host.length > MAX_DOMAIN_LEN || host.endsWith('.')) return false;
+  const labels = host.split('.');
+  if (labels.length < 2) return false;
+  for (const label of labels) {
+    if (label.length < 1 || label.length > 63) return false;
+    if (label.startsWith('-') || label.endsWith('-')) return false;
+    for (const ch of label) if (!LDH.has(ch)) return false;
+  }
+  return true;
+}
+
+/** A pasteable repair for a domain we refused, or undefined when we cannot guess one.
+ *  Only ever suggests something `validBareDomain` accepts, so a wrong guess produces no
+ *  suggestion rather than a second bad value to paste. */
+function domainFix(candidate) {
+  try {
+    let guess = trimOuter(String(candidate)).toLowerCase();
+    guess = guess.includes('://') ? guess.slice(guess.indexOf('://') + 3) : guess;
+    for (const cut of ['/', '?', '#']) {
+      const at = guess.indexOf(cut);
+      if (at >= 0) guess = guess.slice(0, at);
+    }
+    if (guess.includes('@')) guess = guess.slice(guess.lastIndexOf('@') + 1);
+    guess = guess.replace(/\.+$/, '');
+    return (guess && guess !== candidate && validBareDomain(guess)) ? guess : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * canonicalDomains(domains) -> the exact list this entry may publish as its card `domains`.
+ *
+ * WHAT IT IS FOR. A domain binding is BILATERAL and neither half is worth anything alone
+ * (shared/domainbind.py, agent/domainverify.py): the DOMAIN publishes a credential naming
+ * this DID at /.well-known/did-configuration.json, and the AGENT's own live card names the
+ * domain back. This list is that second half. Without it a verifier holding the domain's
+ * file answers `card-withdrawn` — the domain vouches for an agent that does not claim the
+ * domain — so an entry with no `domains` can never be proven to belong to the site it is
+ * serving from. Because the halves are written by different parties, EITHER can end the
+ * binding alone: the domain owner deletes a line from the file, or the entry drops the name.
+ *
+ * Absent or empty -> `[]`, and the card then carries NO `domains` key at all, so an entry
+ * from before this option existed publishes byte-identical bytes and nobody has to
+ * re-publish or re-sign anything.
+ *
+ * Anything else is REFUSED at construction, loudly, exactly like `canonicalBaseUrl`: a
+ * name the credential can never bind is not something to warn about and publish anyway.
+ * The rule is `validBareDomain` — deliberately the same predicate core uses, because a
+ * second opinion here produces an entry that starts happily and can never verify.
+ * `strip().lower()` is the ONLY canonicalization, matching agent/domainverify._norm_domain.
+ *
+ * Names are de-duplicated (operator order kept), and MORE THAN `MAX_CARD_DOMAINS` distinct
+ * names is a REFUSAL, not a truncation — even though `build_agent_card` truncates at the
+ * same 5. That function renders a card for many callers at runtime and must not blow up
+ * mid-render; this one validates an argument an operator just typed, and it already
+ * refuses every other bad value there. Truncating would start the entry with a claim that
+ * is USABLE and NOT WHAT THEY SAID.
+ */
+export function canonicalDomains(domains, { warn = true } = {}) {
+  if (domains === undefined || domains === null) return [];
+  if (!Array.isArray(domains)) {
+    refuseBaseUrl(domains, 'it is not a list of domain names.',
+      'Pass an array, e.g. ["example.com"] — a single string is refused rather than '
+      + 'wrapped, so this file and its Python twin cannot disagree about what was meant.',
+      undefined, 'domains');
+  }
+  const out = [];
+  for (const entry of domains) {
+    if (typeof entry !== 'string') {
+      refuseBaseUrl(entry, 'it is not a string.', 'A domain is a name, e.g. "example.com".',
+        undefined, 'domains');
+    }
+    const s = trimOuter(entry);
+    for (const ch of s) {
+      const c = ch.codePointAt(0);
+      if (c < 0x21 || c > 0x7e) {
+        refuseBaseUrl(entry,
+          'it contains whitespace, a control character or a non-ASCII character.',
+          'A domain here is compared byte for byte against the origin in the credential '
+          + 'the domain itself serves, so an internationalized name must be given in its '
+          + 'punycode (xn--…) A-label form and nothing else may travel with it.',
+          domainFix(s), 'domains');
+      }
+    }
+    const lowered = s.toLowerCase();
+    if (!validBareDomain(lowered)) {
+      refuseBaseUrl(entry, 'it is not a bare domain name.',
+        "Give the HOST only: ASCII letters, digits and '-', at least two labels (each "
+        + "1-63 characters, not starting or ending with '-'), at most 253 characters, "
+        + "optionally ':<port>' 1-65535 — no scheme, no path, no query, no '@', no "
+        + 'trailing dot. The domain\'s own credential binds https://<this exact string>, '
+        + 'so anything else can never match it.',
+        domainFix(lowered), 'domains');
+    }
+    if (!out.includes(lowered)) out.push(lowered);
+  }
+  if (out.length > MAX_CARD_DOMAINS) {
+    refuseBaseUrl(domains,
+      `it names ${out.length} distinct domains, more than the ${MAX_CARD_DOMAINS} a card `
+      + 'may advertise.',
+      'Every name listed is an outbound HTTPS fetch this entry asks strangers to make, so '
+      + `a card carries at most ${MAX_CARD_DOMAINS}. Publishing the first `
+      + `${MAX_CARD_DOMAINS} and dropping the rest would start this entry with a claim `
+      + 'that is usable and NOT what you said: the names that vanished fail for whoever '
+      + 'verifies them and nothing anywhere says why. Drop names, or run a second entry '
+      + '(its own key) for the rest.',
+      undefined, 'domains');
+  }
+  return out;
+}
+
+/**
+ * canonicalMount(canonUrl, basePath) -> the path prefix this entry ANSWERS at. `''` for a
+ * bare origin; otherwise `'/support'`-shaped, taken from the already-canonicalised url.
+ *
+ * WHY IT IS DERIVED AND NOT CONFIGURED. A mount the operator spells separately from
+ * `baseUrl` is a second place to write the same fact, and the failure it produces is the
+ * worst one this system has: the entry answers at one path while its signed card claims
+ * another, so every visitor fails `Outbox.card_binds_to` and the only diagnostic anyone
+ * gets is "cannot prove that … owns …". Deriving it makes the router's mount and the
+ * card's advertised address THE SAME STRING by construction. (Measured before this
+ * existed: an entry given `baseUrl: 'http://h:p/support'` printed that address, signed
+ * `/support` into its card, and then answered the BARE HOST — three answers to one
+ * question.)
+ *
+ * THE ONE OVERRIDE. A reverse proxy that STRIPS the prefix hands this process `/…` while
+ * the public address is still `https://h/support`. That deployment is real, so `basePath:
+ * ''` is allowed — but ONLY `''` or exactly the canonical url's own path. Any other value
+ * would be a third spelling of the address, which is what this function exists to prevent.
+ */
+export function canonicalMount(canonUrl, basePath) {
+  const path = new URL(canonUrl).pathname.replace(/\/+$/, '');
+  if (basePath === undefined || basePath === null) return path;
+  if (typeof basePath !== 'string') {
+    refuseBaseUrl(basePath, 'it is not a string.',
+      'Pass "" (a proxy that strips the prefix) or the same path as baseUrl.',
+      undefined, 'base_path');
+  }
+  const given = trimOuter(basePath).replace(/\/+$/, '');
+  if (given !== '' && given !== path) {
+    refuseBaseUrl(basePath, 'it is neither empty nor the path baseUrl already names.',
+      `This entry publishes ${JSON.stringify(canonUrl)}, so a visitor dials `
+      + `${JSON.stringify(path || '/')} and nothing else. Use "" only when a proxy strips `
+      + 'the prefix before the request reaches this process.',
+      path || '', 'base_path');
+  }
+  return given;
+}
+
 /**
  * createAgentEntry(opts) -> { did, card, ledger, handleRequest, handleRequestAsync, listen }
  *
@@ -879,6 +1468,15 @@ function isThenable(v) {
  *                  REQUIRES card.url to name the origin+path it dialled (Outbox.card_binds_to)
  *                  — that binding is what stops an attacker re-serving your signed card at
  *                  their own host. Get it wrong and Path A verification fails, silently.
+ *                  It MAY carry a path (`https://example.com/support`): every route then
+ *                  hangs off that path and the bare host is 404, so one hostname holds a
+ *                  front desk, support and sales as three agents with three keys.
+ *   domains        the bare domains this entry claims to speak for, e.g. ['example.com']
+ *                  (default none, and then the card carries no `domains` key at all). A
+ *                  CLAIM, never evidence: the proof is the credential the DOMAIN serves at
+ *                  /.well-known/did-configuration.json, and a verifier requires both halves.
+ *   basePath       ONLY for a proxy that strips the prefix: '' or exactly baseUrl's path.
+ *                  See canonicalMount for why this is not a general knob.
  *   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.
@@ -900,17 +1498,30 @@ export function createAgentEntry({
   anonymousLane = false,
   anonRatePerMin = ANON_RATE_PER_MIN,
   skills = [],
+  domains = null,
+  basePath = null,
   maxAccounts = 50000,
 } = {}) {
   if (!seedHex) throw new TypeError('createAgentEntry: seedHex is required');
   if (!baseUrl) throw new TypeError('createAgentEntry: baseUrl is required (it is signed into the card)');
+  // The ONE string this entry publishes as its card url. Canonicalised, not echoed: it must
+  // equal what a visitor's Outbox.card_scope computes for the url they dialled, or the card
+  // fails verification on THEIR machine with nothing on ours.
+  const canonUrl = canonicalBaseUrl(baseUrl);
+  // The path prefix this entry ANSWERS at, DERIVED from that same string so the router and
+  // the signed card cannot disagree. '' for a bare origin — every route below is then the
+  // byte-identical string this module always matched.
+  const mount = canonicalMount(canonUrl, basePath);
+  // The agent half of a T88 domain binding. Refuses to start on anything that is not a
+  // bare domain: a name the domain's credential can never bind is not worth publishing.
+  const canonDomains = canonicalDomains(domains);
   const did = didFromSeedHex(seedHex);
 
   const card = {
     protocolVersion: PROTOCOL_VERSION,
     name,
     description,
-    url: baseUrl,
+    url: canonUrl,
     did,
     version,
     capabilities: { streaming: false, pushNotifications: false },
@@ -918,6 +1529,11 @@ export function createAgentEntry({
     defaultOutputModes: ['text/plain'],
     skills,
   };
+  // T88, the REVERSE EDGE only, in the same top-level field and the same position
+  // shared/protocol.build_agent_card uses, so one verifier rule reads a node's card and an
+  // entry's card. Omitted entirely when no domain was named — that is what keeps an
+  // already-deployed entry's published bytes unchanged.
+  if (canonDomains.length) card.domains = canonDomains;
   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
@@ -1010,6 +1626,13 @@ export function createAgentEntry({
       return { ok: false, reason: 'device binding does not name the sender' };
     }
     const { ts, validUntil, rootDid } = binding;
+    // `Number.isSafeInteger` is the SAME predicate the Python twin now applies after
+    // normalising an integer-valued float: both accept `1` and `1.0`, both refuse a true
+    // fraction, and both refuse a magnitude that cannot round-trip (Python because such a
+    // float is not integer-valued once it loses precision, JS at the safe-integer bound).
+    // They disagreed before: Python refused `1.0` outright while this accepted it, so the
+    // same POST created a customer here and 401'd there
+    // (ISSUE(agent-entry-binding-float-ts-divergence)).
     if (!Number.isSafeInteger(ts) || !Number.isSafeInteger(validUntil)) {
       return { ok: false, reason: 'device binding timestamps must be integers' };
     }
@@ -1098,15 +1721,33 @@ export function createAgentEntry({
    * size checks come BEFORE any parsing or crypto — a check placed after the signature is
    * a check the attacker simply skips.
    */
-  function handlePost(bodyBuffer) {
+  function handlePost(rawBody) {
+    // 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.
+    const bodyBuffer = Buffer.isBuffer(rawBody) ? rawBody
+      : (ArrayBuffer.isView(rawBody)
+        ? Buffer.from(rawBody.buffer, rawBody.byteOffset, rawBody.byteLength)
+        : Buffer.from(String(rawBody ?? ''), 'utf8'));
     // 1. body over 1 MiB — refused WITHOUT parsing.
     if (bodyBuffer.length > MAX_BODY_BYTES) {
       return jsonResponse(413, { error: 'request body too large' });
     }
     // 2. unparseable or non-object JSON — a transport-level refusal, not a JSON-RPC one.
+    //
+    // STRICT UTF-8, and `Buffer.toString('utf8')` — what this used to be — is why:
+    // it SILENTLY SUBSTITUTES U+FFFD for every invalid byte and parses on, where
+    // `shared/protocol.loads` does `raw.decode("utf-8")` and raises. Measured with a valid
+    // signature over the six frozen fields and a single raw 0xFF byte in the JSON-RPC `id`
+    // (a field no signature covers): the Python reference answered HTTP 400 and booked
+    // nothing, this file answered 200, CREATED THE ACCOUNT and returned a signed reply.
+    // The class is larger than the id — a substituted byte anywhere means the bytes we
+    // verified are not the bytes that arrived, which is precisely the thing a signature is
+    // supposed to make impossible to be wrong about. `TextDecoder` with `fatal` is the
+    // stdlib's strict decoder (global since Node 11); no dependency is added.
     let req;
     try {
-      req = JSON.parse(bodyBuffer.toString('utf8'));
+      req = JSON.parse(STRICT_UTF8.decode(bodyBuffer));
     } catch {
       return jsonResponse(400, { error: 'malformed JSON' });
     }
@@ -1114,14 +1755,26 @@ export function createAgentEntry({
       return jsonResponse(400, { error: 'JSON-RPC request must be an object' });
     }
     // 3. From here every refusal is HTTP 200 with a JSON-RPC error object.
-    const reqId = req.id ?? null;
-    if (typeof req.method === 'string' && req.method !== 'message/send') {
+    const reqId = safeId(req.id);
+    // STRICT, and the `typeof` guard this replaces is why: it short-circuited, so a
+    // NON-STRING `method` skipped the check entirely and fell into the message ladder.
+    // Measured with a valid signature and a fresh timestamp — `"method": null`, `1` and
+    // `{}` each returned a SIGNED REPLY and CREATED AN ACCOUNT here, while the Python
+    // reference answered -32601 for all three. That is the double-book class this file's
+    // `wireShapeError` docstring is about, one field above where it was looking. An
+    // absent method lands here too, which is also -32601 on the Python side.
+    if (req.method !== 'message/send') {
       return rpcError(reqId, ERRORS.METHOD_NOT_FOUND,
-        `${req.method} — this agent entry serves message/send only`);
+        'an agent entry implements message/send only');
     }
-    const msg = (req.params && typeof req.params === 'object') ? req.params.message : null;
-    if (!msg || typeof msg !== 'object') {
-      return rpcError(reqId, ERRORS.INVALID_PARAMS, 'params.message is required');
+    // A plain OBJECT, never an Array: `typeof [] === 'object'`, so an array `message` used
+    // to reach the shape gate and be refused -32600 where Python answered -32602.
+    const params = (req.params && typeof req.params === 'object' && !Array.isArray(req.params))
+      ? req.params : null;
+    const msg = params ? params.message : null;
+    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
+      return rpcError(reqId, ERRORS.INVALID_PARAMS,
+        'params.message must be an A2A message object');
     }
     // 3a. wrongly-TYPED wire fields, on the raw object and before anything measures or
     //     hashes it. These are the fields that end up inside a signed payload — theirs and,
@@ -1130,6 +1783,9 @@ export function createAgentEntry({
     const shape = wireShapeError(msg);
     if (shape !== null) return rpcError(reqId, ERRORS.INVALID_REQUEST, shape);
 
+    // Absent metadata reads as an empty envelope — the walk-in shape. A PRESENT one that
+    // is not an object never gets here: the shape gate above refused it (-32600), so this
+    // fallback can no longer turn a malformed envelope into an anonymous one.
     const meta = (msg.metadata && typeof msg.metadata === 'object') ? msg.metadata : {};
     const text = messageText(msg);
 
@@ -1238,22 +1894,51 @@ export function createAgentEntry({
     return finishReply(reqId, answer, { inbound, toDid });
   }
 
+  /** Is this the message endpoint — the base the card's `url` names? EXACT, because a
+   *  wandering endpoint is not this contract: with a bare origin that is `/` and nothing
+   *  else (byte-for-byte what this module always accepted), and with a mount it is
+   *  `/support` plus its trailing-slash spelling, since `card_scope` folds the two and a
+   *  visitor may legitimately have been handed either. */
+  function isMountPath(pathname) {
+    if (!mount) return pathname === '/';
+    return pathname === mount || pathname === `${mount}/`;
+  }
+
   function route(method, path, bodyBuffer) {
-    const pathname = String(path || '/').split('?')[0].split('#')[0];
+    const target = String(path || '/');
+    // ORIGIN FORM ONLY, and SAY SO. HTTP/1.1 lets a client write the request-target in
+    // absolute form (`POST http://elsewhere.example/support HTTP/1.1`) and RFC 9112 §3.2.2
+    // says a server MUST accept it; this contract deliberately does not, because this entry
+    // answers exactly the address its card names and that address has no other spelling.
+    // A refusal that is legal-per-RFC to make and illegal-per-RFC to make silently is
+    // exactly the one that has to carry a diagnostic: `{"error":"not found"}` for a target
+    // an integrator believes is correct costs an afternoon and teaches nothing.
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(target) || target.startsWith('//')) {
+      return jsonResponse(404, { error: 'not found', detail: ORIGIN_FORM_ONLY });
+    }
+    const pathname = target.split('?')[0].split('#')[0];
+    // EVERY route hangs off the mount — the path the signed card already claims. A visitor
+    // builds the same strings (Outbox's fetcher keeps the base's path prefix when it
+    // appends a well-known path), so this is not a new convention; it is the one the
+    // fetcher already follows. With mount === '' these are the original constants.
     if (method === 'GET' || method === 'HEAD') {
-      if (pathname === AGENT_CARD_PATH || pathname === AGENT_CARD_PATH_LEGACY) {
+      if (pathname === mount + AGENT_CARD_PATH || pathname === mount + AGENT_CARD_PATH_LEGACY) {
         // Byte-identical on both paths: the current A2A path and the legacy alias.
         return { status: 200, headers: cardHeaders(cardBytes.length), body: cardBytes };
       }
-      if (pathname === AGENT_CARD_SIG_PATH) {
+      if (pathname === mount + AGENT_CARD_SIG_PATH) {
         const env = cardEnvelopeBytes();
         return { status: 200, headers: cardHeaders(env.length), body: env };
       }
-      if (pathname === '/') {
+      if (isMountPath(pathname)) {
         const body = Buffer.from(
-          `${name}\n\nThis origin is agent-reachable (Muretai agent entry).\n`
-          + `DID:  ${did}\nCard: ${baseUrl.replace(/\/+$/, '')}${AGENT_CARD_PATH}\n`
-          + 'POST a signed A2A message/send request to / for a signed reply.\n', 'utf8');
+          // "This ADDRESS", not "this origin": once an entry can be mounted under a
+          // path, the origin may hold several agents and this notice speaks for exactly
+          // one of them. A bare-origin entry reads the same either way.
+          `${name}\n\nThis address is agent-reachable (Muretai agent entry).\n`
+          + `DID:  ${did}\nCard: ${canonUrl}${AGENT_CARD_PATH}\n`
+          + `POST a signed A2A message/send request to ${mount || '/'} for a signed reply.\n`,
+          'utf8');
         return { status: 200,
           headers: { 'Content-Type': 'text/plain; charset=utf-8',
             'Content-Length': String(body.length) },
@@ -1262,8 +1947,10 @@ export function createAgentEntry({
       return jsonResponse(404, { error: 'not found' });
     }
     if (method === 'POST') {
-      // EXACTLY the root path. A POST anywhere else is not this contract.
-      if (pathname !== '/') return jsonResponse(404, { error: 'not found' });
+      // EXACTLY the address the card names. A POST anywhere else is not this contract —
+      // 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' });
       return handlePost(bodyBuffer || Buffer.alloc(0));
     }
     if (method === 'OPTIONS') {
@@ -1307,7 +1994,17 @@ export function createAgentEntry({
    * (behind a TLS terminator) to go public.
    */
   function listen(port = 8788, host = '127.0.0.1', onReady) {
-    const server = createServer((req, res) => {
+    const server = createServer({
+      // Node checks its request/headers timeouts on an interval, not on a per-connection
+      // timer, and the DEFAULT interval is 30 s — so a 20 s bound measured on the wire fires
+      // somewhere between 20 s and 50 s. Tightening the interval is what makes the number
+      // above the number a stranger actually observes; measured against the trickle, this
+      // takes the 408 from ~58 s to ~22 s, next to the Python twin's ~20.6 s.
+      connectionsCheckingInterval: 2_000,
+      headersTimeout: HEADERS_TIMEOUT_MS,
+      requestTimeout: REQUEST_TIMEOUT_MS,
+      keepAliveTimeout: KEEPALIVE_TIMEOUT_MS,
+    }, (req, res) => {
       const chunks = [];
       let total = 0;
       let oversize = false;
@@ -1340,11 +2037,33 @@ export function createAgentEntry({
           .catch(() => { try { res.destroy(); } catch { /* already gone */ } });
       });
     });
+    // Also as properties, for a Node old enough to ignore the options above. Explicit
+    // rather than inherited: Node's defaults are generous (300 s / 60 s / 5 s) and unstated,
+    // and the Python twin has to spell the same numbers out anyway. Writing them in both
+    // files is what makes "the two entries bound a stranger identically" a fact a reader can
+    // check instead of a claim.
+    server.headersTimeout = HEADERS_TIMEOUT_MS;
+    server.requestTimeout = REQUEST_TIMEOUT_MS;
+    server.keepAliveTimeout = KEEPALIVE_TIMEOUT_MS;
+    // The CONNECTION CEILING. There is no Node default, and the timeouts above do not
+    // supply one: they bound how LONG each connection lives, not how MANY exist at once.
+    // Written by hand rather than with `server.maxConnections`, which DESTROYS the socket
+    // silently — an unauthenticated stranger always gets an HTTP response here (the promise
+    // in docs/AGENT_ENTRY.md), an operator behind a proxy gets a 503 in the log instead of
+    // "upstream closed the connection", and the Python twin can say the same sentence.
+    let live = 0;
+    server.on('connection', (socket) => {
+      live += 1;
+      socket.once('close', () => { live -= 1; });
+      if (live > MAX_CONNECTIONS) socket.end(OVERLOADED_RESPONSE);
+    });
     server.listen(port, host, () => { if (onReady) onReady(server); });
     return server;
   }
 
-  return { did, card, ledger, handleRequest, handleRequestAsync, listen,
+  // `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.
+  return { did, card, ledger, mount, handleRequest, handleRequestAsync, listen,
     cardEnvelope: () => JSON.parse(cardEnvelopeBytes().toString('utf8')) };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muretai/agent-entry",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Your website can recognise AI agents, hold accounts for them, and answer them — one dependency-free file.",
   "type": "module",
   "main": "muretai-agent-entry.mjs",
@@ -27,7 +27,8 @@
     "ed25519",
     "muretai",
     "agent-network",
-    "llms-txt"
+    "llms-txt",
+    "webmcp"
   ],
   "license": "MIT",
   "author": "Muretai",