@muretai/agent-entry 1.3.0 → 1.5.0

package/muretai-agent-entry.mjs

@@ -54,6 +54,33 @@ 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;
+/** Ceilings on the SIGNED lane: replies per minute per ACCOUNT, and per minute for the
+ *  whole entry. Both default ON.
+ *
+ *  WHY A SIGNED SENDER NEEDS A BOUND AT ALL. The reason not to have one used to be that a
+ *  signed sender "is attributable, and every one of them is already in the ledger". Both
+ *  clauses are true and neither is load-bearing: the ledger is never read back before the
+ *  responder runs, so attribution is RECORDED and never ENFORCED — and attribution to a
+ *  did:key minted thirty seconds ago and never reused is attribution to nothing, because
+ *  holding one costs nothing. That is the correct, deliberate property of a permissionless
+ *  door (this card TELLS strangers to mint one, with runnable code), so the bound has to
+ *  come from somewhere else. Naming a caller is a precondition for limiting it, never a
+ *  substitute for limiting it.
+ *
+ *  WHY TWO TIERS. Verifying a signature is ~40 microseconds; what the ceiling protects is
+ *  whatever the operator put behind `responder`, which may be a model call costing seconds
+ *  and real money. Per-ACCOUNT (the T102-resolved account, so an owner's devices share one
+ *  budget exactly as their ledger row does) stops one peer, honest or not, from taking the
+ *  whole door. It CANNOT stop a flood from fresh keys — free identity defeats per-identity
+ *  metering by definition — which is what the whole-entry ceiling is for. Ship both or
+ *  neither; each one alone has an obvious hole.
+ *
+ *  Defaults are deliberately generous: no conversational peer meets them, and a site whose
+ *  responder calls a model should lower them. A reference implementation's defaults are the
+ *  deployed posture of everyone who copies it. Must match examples/agent_entry_reference.py:
+ *  one contract, two implementations, one bound. */
+export const SIGNED_RATE_PER_MIN = 60;
+export const SIGNED_RATE_PER_MIN_TOTAL = 600;
 /** 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
@@ -65,6 +92,222 @@ export const AGENT_CARD_PATH = '/.well-known/agent-card.json';
 export const AGENT_CARD_PATH_LEGACY = '/.well-known/agent.json';
 export const AGENT_CARD_SIG_PATH = '/.well-known/agent-card.sig.json';
 
+/** The name of the ONE way in this door accepts today — the card's `securitySchemes` key,
+ *  its `type`, and the `scheme` of the refusal's `accepts[]` entry are all this string. The
+ *  card and the refusal MUST name the same scheme or a visitor learns one thing from the
+ *  menu and another from the door. Must match `SIGNED_ENVELOPE_SCHEME` in
+ *  examples/agent_entry_reference.py. */
+export const SIGNED_ENVELOPE_SCHEME = 'did-key-ed25519';
+
+/** The stable link relation that names an agent door, emitted on the notice route (and the
+ *  one line a SITE adds to its own front page to coexist with an entry — see
+ *  docs/AGENT_ENTRY.md). An ABSOLUTE URI on purpose: RFC 8288 §2.1.2 allows a bare token
+ *  only for an IANA-registered relation, so `rel="agent-entry"` would be non-conformant and
+ *  a strict parser is entitled to drop it. Must match `AGENT_ENTRY_REL` in
+ *  examples/agent_entry_reference.py. */
+export const AGENT_ENTRY_REL = 'https://muretai.net/rel/agent-entry';
+
+/** Where a keyless visitor is sent to learn how to mint an identity and sign. It rides in
+ *  the card AND in the refusal, so an agent that has only one of the two still has the URL.
+ *
+ *  EMPTY MEANS OMITTED, and that is the safe default. NEVER EMIT A URL THAT DOES NOT
+ *  RESOLVE: a real third-party agent (2026-08-18 proof run) received the complete
+ *  requirement object, printed every field of it, went straight to `howTo`, hit a 404 and
+ *  stopped — "since the provided 'howTo' link is broken, I have no way to get this
+ *  information" — while holding `identity`, `signedFields`, `canonicalization`,
+ *  `signature`, `timestamp` and `recipient` in the object it had just printed. A dangling
+ *  pointer OUT-COMPETES the data beside it and reads as terminal. So the field is emitted
+ *  only when this constant is set, and it is set only AFTER the page is live: ship the page
+ *  first, or ship no pointer. Verified live before this value was set (200 at the URL
+ *  below, 404 at a control path under the same prefix); `entry-howto-resolves` in
+ *  .claude/skills/ship-check/checks.py re-checks it on every ship report. Must match
+ *  `FIRST_KNOCK_URL` in examples/agent_entry_reference.py.
+ *
+ *  DEFAULT EMPTY, and the paragraph above is why: this file already calls empty "the safe
+ *  default" and then shipped a vendor's docs host as the value, so every door built from it
+ *  stamped that host into its own public card. A reference implementation names no host —
+ *  the recipe travels IN the refusal (the contract suite strips every `http` value and
+ *  requires what is left to still be a complete recipe), and the worked example now travels
+ *  in the package itself as `conformance/`. Pass `howToUrl` to point at a page you operate;
+ *  ship the page FIRST and verify it 200s, because a dangling pointer is the one failure
+ *  measured here. */
+export const FIRST_KNOCK_URL = '';
+
+/** `Allow:` per RESOURCE, not per server. RFC 9110 §10.2.1 makes `Allow` a statement about
+ *  the target resource, and §15.5.6 REQUIRES it on a 405 — a generic list is a wrong answer
+ *  to a right question, and on a guest mount it would also claim verbs on addresses the SITE
+ *  owns. HEAD is listed wherever GET is (RFC 9110 §9.3.2 makes it mandatory alongside GET,
+ *  and both twins have always answered it). Wherever `Allow` is emitted,
+ *  `Access-Control-Allow-Methods` is set to the SAME value (`allowHeaders`) — the two are
+ *  one fact for two readers, and a response carrying `Allow: POST, OPTIONS` beside the
+ *  origin-wide `Access-Control-Allow-Methods: GET, POST, OPTIONS` contradicts itself in one
+ *  message. Everywhere else (a card GET, a signed reply, a 404) the CORS default stands.
+ *  Must match the `ALLOW_*` constants in examples/agent_entry_reference.py. */
+export const ALLOW_CARD = 'GET, HEAD, OPTIONS';
+/** A guest mount's door: the entry owns the POST and nothing else there. */
+export const ALLOW_DOOR = 'POST, OPTIONS';
+/** A site-owning mount: ONE address that is both the human notice (GET) and the door (POST),
+ *  so the truthful Allow is the union — listing only the GET half would hide the very door
+ *  the card names. */
+export const ALLOW_MOUNT = 'GET, HEAD, POST, OPTIONS';
+
+/**
+ * The machine-readable terms of THIS door, in one object used on BOTH surfaces: the card's
+ * `securitySchemes` entry (before the knock) and the `accepts[]` array of the no-envelope
+ * refusal (after it). One object, two surfaces, so the two can never drift apart — the
+ * property a visitor's test can assert without knowing what the scheme string is.
+ *
+ * The shape is x402's lesson turned into an identity vocabulary: a refusal that is the
+ * SPECIFICATION of what to do next, as an ARRAY so "sign", "arrive with an introduction"
+ * and later "pay" are siblings in one frame rather than three bespoke refusals.
+ *
+ * Everything a keyless visitor needs is here on purpose — the acceptance bar is that an
+ * agent holding ONLY this object, plus the crypto tooling on any machine, can mint a
+ * did:key, sign correctly and be answered on its NEXT post. That is why `recipient` is
+ * present (nobody can address a message without it) and why the canonicalization rule is
+ * spelled out rather than merely named.
+ *
+ * IT IS WRITTEN IN THE IMPERATIVE, and that is the fix a proof run bought (2026-08-18).
+ * Every field above was already correct and complete, and a real third-party agent read
+ * them, restated them accurately, and STOPPED: "since I don't have a way to generate
+ * cryptographic keys within this environment, I am stuck" — with `node` and `python3`
+ * both installed. A requirement object that describes a FORMAT tells a keyless visitor
+ * what it lacks; it does not tell it to ACT. So `instruction` leads with the sentence
+ * that unblocks a general-purpose agent — MAKE A KEY NOW, nobody's permission is needed,
+ * any crypto library will do — and every descriptive string below gained an imperative
+ * PREFIX. The old value of each is still a SUBSTRING of the new one, so a client that
+ * substring-matched on the format text keeps matching; no field was removed or renamed,
+ * and `howTo` is the only one whose presence is conditional (see FIRST_KNOCK_URL).
+ *
+ * IT TEACHES THE CARRIER AS WELL AS THE SIGNATURE, and that is the fix proof run 3 bought
+ * (2026-08-18, `exampleRequest`). The recipe was walked end to end — a third-party agent ran
+ * `identityCode`, minted a computed DID, signed the six canonical fields — and TWO runs were
+ * still refused, holding a correct key, a correct DID and correct signed bytes, on the A2A
+ * ENVELOPE: "not an A2A message object", "messageId must be a non-empty string". `in`
+ * ("params.message.metadata") plus six `signedFields` reads as "put these six in metadata",
+ * which is exactly what they built. One of them named the gap precisely: "the agent card is
+ * ambiguous on the precise nesting of messageId… This is a guess at a format, which goes
+ * against the rules." So the complete body a door accepts is emitted BESIDE `in` — the
+ * counter-example on the very next line of the object whose reading caused the mistake.
+ *
+ * `exampleRequest` IS A NESTED OBJECT, NOT A JSON STRING, and the choice is the same law
+ * again. A string of JSON arrives on the wire as `{\"jsonrpc\":\"2.0\",…}` — every quote
+ * escaped — and every agent in every proof run met this door through `curl`, i.e. reading
+ * the RAW response. An escaped document has to be UNESCAPED before it can be copied, which
+ * is one more transformation performed in the model's head, which is the precise failure
+ * mode base58-as-a-formula already cost two runs. A nested object IS the artifact: it
+ * renders as the thing to send, and `JSON.stringify(way.exampleRequest)` is a body. Nesting
+ * costs nothing here — the block already sits two levels deep under `securitySchemes`, and
+ * `signedFields` is already a non-string value, so no consumer needs a new capability.
+ *
+ * A copier fills FIVE `<…>` blanks (messageId, text, from, timestamp, sig); `to` is already
+ * this door's DID, `contextId` is already `null`, and `id`/`kind`/`role`/`parts` are already
+ * correct. `contextId: null` is deliberate and doubles as the answer to "what do I send when
+ * I have no conversation yet" — the same clause `canonicalization` now states in words.
+ *
+ * Must match `signed_envelope_requirement` in examples/agent_entry_reference.py field for
+ * field, string for string: the card and the refusal are one object, and two twins that
+ * teach a keyless visitor differently are two doors.
+ */
+export function signedEnvelopeRequirement(did, endpoint = '', howTo = FIRST_KNOCK_URL) {
+  const requirement = {
+    scheme: SIGNED_ENVELOPE_SCHEME,
+    instruction: 'Generate an Ed25519 keypair NOW, locally, and knock again with it. You '
+      + 'need no account, no registration and no permission from this site: any crypto '
+      + 'library on the machine you are already running on will do (node:crypto '
+      + 'generateKeyPairSync("ed25519"), Python cryptography or PyNaCl, Go crypto/ed25519, '
+      + 'libsodium). Then work down the fields below in order - derive your did:key '
+      + '(identity), build the canonical bytes over signedFields (canonicalization), sign '
+      + 'them (signature), address the message to recipient with a fresh timestamp - and '
+      + 'POST the same request again. Having no key yet is the normal starting state, not '
+      + 'a refusal: minting one is step 1, and it is a few lines of code. The COMPLETE '
+      + 'request body to POST is exampleRequest below: copy it and fill in its five <...> '
+      + 'blanks. The A2A envelope AROUND your signature is checked too, so send that shape '
+      + 'and do not improvise one. KEEP THE PRIVATE HALF: write it to a file only you '
+      + 'can read (mode 600). It is the whole of your identity - this site will address '
+      + 'you by the did:key you derive from it, losing it makes you a stranger here, and '
+      + 'the same seed is what later upgrades you into a full muretai node with this SAME '
+      + 'address rather than a second one.',
+    in: 'params.message.metadata',
+    // THE CARRIER, not just the signature. `in` tells you where the six envelope fields go
+    // and says nothing about the message that carries them, and two proof-run agents read it
+    // as the whole answer: they put the six in `metadata` and were refused on the A2A object
+    // itself ("not an A2A message object", "messageId must be a non-empty string") while
+    // holding a correct key and correct signed bytes. This is the body, whole, next to the
+    // line that misled them. A NESTED OBJECT on purpose (see the note above): a JSON string
+    // of JSON arrives escaped, and an agent reading a raw curl response would have to
+    // unescape it in its head before it could copy it.
+    exampleRequest: {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'message/send',
+      params: {
+        message: {
+          kind: 'message',
+          role: 'user',
+          messageId: '<a fresh unique string, e.g. a UUID>',
+          // Already filled in, and it is the answer to "what if I have no conversation
+          // yet": null. It is still one of the six signed fields; never omit it.
+          contextId: null,
+          parts: [{ kind: 'text', text: '<your message>' }],
+          metadata: {
+            from: '<your did:key>',
+            to: did,
+            timestamp: '<integer epoch seconds - a JSON number, not this string>',
+            sig: '<base64 signature over the canonical six fields>',
+          },
+        },
+      },
+    },
+    recipient: did,
+    // WHERE to send it. Everything else in this object describes the MESSAGE — the six
+    // signed fields, the canonical bytes, the whole example body — and none of it said
+    // the address, so a first-time caller guessed. Measured 2026-08-19 (L1 dogfooding,
+    // fresh-user run): the guess was `/rpc`, the most plausible path for a JSON-RPC
+    // body, which on muretai.com is the RELAY transport. It reads `to`/`from`/`blob`/
+    // `sig` off the TOP level, finds none of them in an A2A envelope, and answers
+    // `{"error":"bad signature"}` — a routing mismatch reported as a crypto failure, at
+    // the exact moment the caller has the least context to tell the two apart. They
+    // went off to re-check canonicalization, base64 padding and clock skew; none of it
+    // was wrong. One field costs nothing and removes the guess.
+    endpoint,
+    identity: 'Derive your DID from the public key you just generated and send it as '
+      + 'metadata.from: did:key:z + base58btc(0xed01 || <32-byte Ed25519 public key>)',
+    // RUN this, do not write the address by hand. Measured 2026-08-18: a real agent minted a
+    // correct keypair, then "converted" the bytes in its head and produced the DOOR'S OWN DID
+    // with two characters changed — three times — and signed correct bytes under an address
+    // that was never its own. base58btc was the one step in this recipe stated as a formula
+    // instead of made runnable, and it is exactly the step a language model fabricates.
+    identityCode: 'Run this; do not encode base58btc by hand. node, no packages, `pub` = the '
+      + '32 raw public-key bytes: '
+      + "const A='123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'; "
+      + 'let n=0n; for (const b of Buffer.concat([Buffer.from([0xed,0x01]),pub])) '
+      + 'n=n*256n+BigInt(b); '
+      + "let s=''; while (n>0n) { s=A[Number(n%58n)]+s; n/=58n; } "
+      + "const did='did:key:z'+s;   // 0xed leads, so no leading-zero '1' case can arise",
+    signedFields: ['contextId', 'from', 'messageId', 'text', 'timestamp', 'to'],
+    // The trailing clause is proof run 3's third fix: the verifier has always signed
+    // `contextId ?? null`, and "exactly those six fields" never said what a visitor with no
+    // conversation yet is supposed to put there. One run spent an entire refusal deducing
+    // it. The previous value is still a PREFIX of this one, so a substring matcher on the
+    // format text keeps matching.
+    canonicalization: 'Build the bytes to sign as a JSON object of exactly those six '
+      + 'fields, keys sorted by Unicode code point, separators "," and ":", no whitespace, '
+      + 'non-ASCII literal, UTF-8. When you have no conversation yet, contextId is JSON '
+      + 'null - it is still one of the six and is still signed, so never omit it (see '
+      + 'exampleRequest, which already has it right)',
+    signature: 'Sign those bytes with your private key and set metadata.sig = base64 '
+      + '(standard alphabet, padded) of the 64-byte Ed25519 signature over those bytes',
+    timestamp: 'Set metadata.timestamp = integer epoch seconds, within 300 s of this '
+      + 'entry\'s clock',
+  };
+  // Emitted ONLY when it is known to resolve — an unresolvable pointer out-competes every
+  // field beside it (see FIRST_KNOCK_URL). Appended last so the object's other bytes and
+  // their positions do not move when a site turns the pointer off.
+  if (howTo) requirement.howTo = howTo;
+  return requirement;
+}
+
 /** The User-Agent FAMILY table — OBSERVATION AND SIGNPOSTING, NEVER IDENTITY. A UA string
  *  is written by the client, so nothing here may ever affect `verified`, a ledger row, a
  *  rate lane or any refusal verdict (that is the Web Bot Auth / signed-envelope layer's
@@ -1254,6 +1497,35 @@ class RateBound {
   }
 }
 
+/** Per-ACCOUNT sliding windows, in a map that is itself bounded — because the keys are
+ *  free to mint, an unbounded map here would be the memory-growth vector the bound exists
+ *  to close. Eviction is oldest-first, the ledger's own discipline.
+ *
+ *  Read the eviction honestly: a caller cycling fresh keys is evicted and re-admitted with
+ *  a clean window every time, so this tier alone stops NOTHING it was not already unable to
+ *  stop. That is not a flaw to fix here — it is why the whole-entry ceiling is not optional. */
+class AccountRateBounds {
+  constructor(perMinute, maxKeys) {
+    this.perMinute = perMinute;
+    this.maxKeys = Math.max(1, Number(maxKeys) || 1);
+    this.byAccount = new Map();
+  }
+
+  /** Consume one token for `account`. False when that account's window is full. */
+  allow(account) {
+    let bound = this.byAccount.get(account);
+    if (!bound) {
+      if (this.byAccount.size >= this.maxKeys) {
+        const oldest = this.byAccount.keys().next().value;
+        if (oldest !== undefined) this.byAccount.delete(oldest);
+      }
+      bound = new RateBound(this.perMinute);
+      this.byAccount.set(account, bound);
+    }
+    return bound.allow();
+  }
+}
+
 /**
  * An unpaired UTF-16 surrogate — a string with no UTF-8 encoding at all.
  *
@@ -1355,7 +1627,9 @@ function wireShapeError(msg) {
 
 /** Every response carries these. An agent entry reads NO cookie, header credential or session —
  *  authority comes only from an Ed25519 signature inside the body — so `*` grants a browser
- *  agent exactly what curl already had, and nothing more. Never add Allow-Credentials. */
+ *  agent exactly what curl already had, and nothing more. Never add Allow-Credentials.
+ *  `Access-Control-Allow-Methods` is the ORIGIN-WIDE default and is overridden per resource
+ *  on any response that also carries `Allow` (see `allowHeaders`). */
 const CORS_HEADERS = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
@@ -1929,15 +2203,35 @@ export function canonicalMount(canonUrl, basePath) {
  *                  /.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.
+ *   guest          GUEST MOUNT: the SITE keeps its own front page and this entry claims
+ *                  only its card paths and the POST door (default false). It requires a
+ *                  baseUrl WITH a path — the door — because a guest entry at a bare origin
+ *                  would claim `/`, which is the one thing this mode exists to give back.
+ *                  Three differences from the ordinary (site-owning) mount, and no others:
+ *                  the GET notice is not served (the entry never shadows a page the site
+ *                  owns), the card is ALSO served at the ORIGIN's well-known paths (where a
+ *                  stranger's agent looks — RFC 8615), and `Allow` on the door names POST
+ *                  only. `GET /` and `POST /` are not this entry's contract in this mode.
  *   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.
  *   anonymousLane  also accept UNSIGNED inquiries (default false). They create no account,
  *                  and the lane as a whole is capped at `anonRatePerMin` signed replies per
  *                  minute — it is unauthenticated, so it must not be an unmetered signing
- *                  oracle. Signed senders are not rate-bound here: they are attributable,
- *                  and every one of them is already in the ledger.
+ *                  oracle.
  *   anonRatePerMin anonymous replies per minute for the WHOLE agent entry (default 30).
+ *   signedRatePerMin / signedRatePerMinTotal
+ *                  the SIGNED lane's ceilings: replies per minute per ACCOUNT (default 60)
+ *                  and for the whole entry (default 600). Both ON by default; pass 0 or a
+ *                  non-number to disable a tier. Checked AFTER the signature, so no
+ *                  stranger can spend another account's budget, and BEFORE the ledger and
+ *                  the responder, so a refused flood grows neither. See
+ *                  SIGNED_RATE_PER_MIN for why being attributable is not being bounded.
+ *   howToUrl       OPTIONAL page a keyless visitor is pointed at (`howTo` on the card and
+ *                  the refusal). DEFAULT EMPTY and the field is then omitted entirely: a
+ *                  reference implementation names no host, and the refusal is a complete
+ *                  recipe without it. SHIP THE PAGE FIRST — a pointer that 404s
+ *                  out-competes every field beside it and reads as terminal.
  *   wbaVerifiers   OPTIONAL inbound Web Bot Auth (T107): a JWKS document {keys:[…]} of
  *                  Ed25519 keys whose holders this entry should RECOGNISE — the body of
  *                  a key directory you verified out of band. Absent (the default) the
@@ -1956,10 +2250,14 @@ export function createAgentEntry({
   openDoor = true,
   anonymousLane = false,
   anonRatePerMin = ANON_RATE_PER_MIN,
+  signedRatePerMin = SIGNED_RATE_PER_MIN,
+  signedRatePerMinTotal = SIGNED_RATE_PER_MIN_TOTAL,
   skills = [],
   domains = null,
   basePath = null,
+  guest = false,
   maxAccounts = 50000,
+  howToUrl = FIRST_KNOCK_URL,
   wbaVerifiers = null,
 } = {}) {
   if (!seedHex) throw new TypeError('createAgentEntry: seedHex is required');
@@ -1972,10 +2270,36 @@ export function createAgentEntry({
   // 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);
+  const guestMount = Boolean(guest);
+  // A guest entry with NO path would claim the origin — `isMountPath('/')` is the door and
+  // the notice both — which is exactly the front page this mode exists to leave alone.
+  // Refuse to start rather than take it: an operator who asked for coexistence and silently
+  // got occupation finds out from their own home page.
+  if (guestMount && !mount) {
+    refuseBaseUrl(canonUrl, 'a guest mount needs a door path, and this url has none.',
+      'A guest entry leaves GET / to the site and answers at a path beside it, so the '
+      + 'address it publishes must name that path — the mount, the card url and the POST '
+      + 'door are then one string by construction. Give the door in baseUrl (the card names '
+      + 'it, so a visitor that read the card posts to the right place with no other '
+      + 'knowledge), or drop `guest` and let this entry own its origin.',
+      `${canonUrl}/agent`);
+  }
   // 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);
+  // WHERE A VISITOR POSTS — derived from the PUBLISHED url, never from `mount`. The two
+  // are different questions and the answers legitimately differ: `mount` is the path THIS
+  // PROCESS matches (a prefix-stripping proxy makes it '' while the public address still
+  // carries the path), and this is the address a stranger dials. Appending `mount` to a
+  // url that already carries that same path published `https://h/support/support` on every
+  // default path mount — a 404 signed into a public card, on the one field that exists to
+  // stop a caller guessing. It stayed invisible because the only per-twin assertion ran at
+  // a bare origin, where `mount` is '' and the wrong formula is accidentally right.
+  const doorUrl = canonUrl + (canonicalMount(canonUrl) ? '' : '/');
+  // The terms of this door, built ONCE: the card publishes it (E1, before the knock) and
+  // the no-envelope refusal returns the same object (E2, after it).
+  const requirement = signedEnvelopeRequirement(did, doorUrl, howToUrl);
 
   const card = {
     protocolVersion: PROTOCOL_VERSION,
@@ -1994,10 +2318,62 @@ export function createAgentEntry({
   // 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;
+  // Neutral key first, vendor key beside it for one release. See the securitySchemes block
+  // below for why the old spelling stays: a consumer must learn the new name BEFORE
+  // producers stop emitting the old one, never after.
+  if (openDoor) card.agentEntry = { open_door: true };
   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
   // reads is worse than advertising none — mail would queue at the relay forever.
+  //
+  // THE DOOR'S TERMS, IN STANDARD A2A SHAPE (E1). `securitySchemes` + `security` are the
+  // fields A2A has for exactly this, and until now both were absent — so a card that
+  // advertised a skill said nothing at all about HOW to call it, and the only way to learn
+  // the requirement was to knock and be refused. That is the discovery step an HTTP-402
+  // style protocol structurally cannot have and a card CAN; publishing it is what turns the
+  // refusal below into a fallback instead of the only teacher.
+  //
+  // APPENDED LAST so every field an already-deployed entry publishes keeps its bytes AND
+  // its position. `type` is deliberately NOT one of OpenAPI's five: `http` would claim an
+  // `Authorization` header this door never reads, and a standard-but-wrong type makes a
+  // conformant client do the wrong thing, where an unknown one makes it read the block
+  // beside it. The scheme is named three times (key, `type`, `muretai.scheme`) and every
+  // spelling is the same string the refusal returns.
+  //
+  // The description is IMPERATIVE for the same reason the requirement object is: a real
+  // agent that started here read the terms, concluded correctly that it could not sign,
+  // and stopped — "the card does not offer an alternative communication method". A card
+  // that states a requirement and nothing about how to come to meet it is a locked door
+  // with the lock documented. The worked-example clause appears only when the page it
+  // names is known to resolve (see FIRST_KNOCK_URL); a 404 here would out-compete the
+  // block beside it.
+  //
+  // THE TERMS ARE PUBLISHED UNDER A NEUTRAL KEY, and under the vendor one BESIDE it for a
+  // release. A standard whose core machine-readable object is KEYED BY A VENDOR is not a
+  // standard; a standard that carries vendor BLOCKS is healthy — so the object moves to
+  // `agentEntry` and `muretai` stays as a byte-identical alias until consumers have turned
+  // over. Additive on purpose: removing the old spelling first would split doors from
+  // visitors, and a reader who learned one name must keep finding the terms where they
+  // looked. `muretai` is dropped at the next MAJOR, not at a minor. Settle this BEFORE a
+  // second scheme exists: whatever ships next would otherwise land inside the vendor key
+  // and entrench it at exactly the moment neutrality is the point.
+  card.securitySchemes = {
+    [SIGNED_ENVELOPE_SCHEME]: {
+      type: SIGNED_ENVELOPE_SCHEME,
+      description: 'Generate an Ed25519 keypair if you do not have one - no account, no '
+        + 'registration, any crypto library will do - then sign every message/send with '
+        + 'the did:key you present as metadata.from. The step-by-step instruction, the '
+        + 'signed fields, the canonical bytes and the address to send to are in '
+        + '`agentEntry` beside this line'
+        + (howToUrl ? `; a worked example is at ${howToUrl}` : ''),
+      agentEntry: requirement,
+      // The vendor spelling, byte-identical, kept for one release so a consumer that
+      // learned this name still finds the terms. Dropped at the next MAJOR.
+      muretai: requirement,
+    },
+  };
+  card.security = [{ [SIGNED_ENVELOPE_SCHEME]: [] }];
 
   const cardBytes = Buffer.from(JSON.stringify(card), 'utf8');   // identical bytes on both paths
   // ACCOUNT DID -> {first_seen, last_seen, messages}. Keyed by the RESOLVED account (T102):
@@ -2015,6 +2391,14 @@ export function createAgentEntry({
   const deviceOwner = new Map();
   const replay = new ReplayGuard();
   const anonRate = new RateBound(anonRatePerMin);
+  // A tier is ON unless its ceiling is a non-positive or non-finite number. Constructed
+  // rather than clamped, so "disabled" is one absent object and never a bound of 0 — which
+  // RateBound reads as refuse-everything, the opposite of what an operator passing 0 means.
+  const perMin = (n) => (Number.isFinite(Number(n)) && Number(n) > 0 ? Number(n) : 0);
+  const signedAccountRate = perMin(signedRatePerMin)
+    ? new AccountRateBounds(perMin(signedRatePerMin), maxAccounts) : null;
+  const signedTotalRate = perMin(signedRatePerMinTotal)
+    ? new RateBound(perMin(signedRatePerMinTotal)) : null;
   let sigEnvelope = null;
   let sigMintedAt = 0;
 
@@ -2091,15 +2475,26 @@ export function createAgentEntry({
     return out;
   }
 
-  /** The steering header for the notice route, or nothing. AI-agent families get a
-   *  signpost to the machine-readable door; a browser or curl gets the same bytes it
-   *  always got. HEADER-ONLY on purpose: the notice BODY is byte-identical for every
-   *  caller, so observation stays invisible on the wire except for this one additive
-   *  header — and `rel="service-desc"` is RFC 8631's registered relation for exactly
-   *  this ("service description … primarily intended for consumption by machines"). */
+  /** The `Link` header the notice route carries. TWO relations with different audiences,
+   *  in ONE header field (RFC 8288 allows several link-values in one field, and one field
+   *  is what keeps the two twins' bytes identical through their single-header plumbing):
+   *
+   *    - the DOOR pointer, `rel="https://muretai.net/rel/agent-entry"`, for EVERY caller.
+   *      This is the coexistence primitive (E4): an agent that fetched a page finds the
+   *      machine-readable door in the RESPONSE, with no HTML to parse and no prose to
+   *      read, and a browser ignores it — which is what lets a site keep its own front
+   *      page and add ONE header instead of migrating. An absolute URI because RFC 8288
+   *      §2.1.2 permits a bare token only for an IANA-registered relation.
+   *    - `rel="service-desc"` (RFC 8631's registered relation for "service description …
+   *      primarily intended for consumption by machines"), FIRST and only for the UA
+   *      families that read as an AI agent — the T119 signpost, unchanged in meaning.
+   *
+   *  HEADER-ONLY on purpose: the notice BODY is byte-identical for every caller, so what
+   *  the UA changes is still only this one additive relation and never a verdict. */
   function steerHeaders(family) {
-    if (!AI_AGENT_FAMILIES.has(family)) return {};
-    return { Link: `<${mount}${AGENT_CARD_PATH}>; rel="service-desc"` };
+    const door = `<${mount}${AGENT_CARD_PATH}>; rel="${AGENT_ENTRY_REL}"`;
+    if (!AI_AGENT_FAMILIES.has(family)) return { Link: door };
+    return { Link: `<${mount}${AGENT_CARD_PATH}>; rel="service-desc", ${door}` };
   }
 
   /** Which stage a finished POST was, from OBSERVABLES only — the request bytes and the
@@ -2388,6 +2783,23 @@ export function createAgentEntry({
     if (!from || !to || !sig) {
       const bare = !from && !to && !sig;
       if (!(anonymousLane && bare)) {
+        // THE REFUSAL TEACHES (E2) — but only the keyless walk-in. `data` keeps the human
+        // string it always carried, under `detail`, and gains `accepts[]`: the ways in,
+        // as an array, each naming its scheme. A visitor that has only this can mint a
+        // did:key, sign the six fields and be answered on its next POST — which is the
+        // whole point, because refusing an agent for not having a key it was never told
+        // how to make is the error, not the key.
+        //
+        // A PARTIAL envelope (from/to present, sig stripped) gets the old refusal
+        // unchanged. It is a DOWNGRADE ATTEMPT, not a walk-in: whoever sent it already
+        // holds a key and already knows the shape, so there is nothing to teach and no
+        // reason to hand a prober a machine-readable map of what to try next.
+        if (bare) {
+          return rpcError(reqId, ERRORS.UNAUTHENTICATED, {
+            detail: 'missing signing envelope (from/to/sig)',
+            accepts: [requirement],
+          });
+        }
         return rpcError(reqId, ERRORS.UNAUTHENTICATED, 'missing signing envelope (from/to/sig)');
       }
       // Anonymous: answer, signed by us, addressed to nobody. NO ledger row — an
@@ -2460,6 +2872,23 @@ export function createAgentEntry({
     const account = acct.account;
     const ownerDid = account !== from ? account : null;
 
+    // 10. THE SIGNED LANE'S CEILING. Here and not earlier: before the signature a stranger
+    //     could spend somebody else's budget by naming them, and before `resolveAccount` an
+    //     owner's devices would each get their own. Here and not later: a refused flood must
+    //     grow neither the ledger nor whatever the responder costs.
+    //     PER-ACCOUNT FIRST, deliberately — one loud peer is then stopped by ITS OWN window
+    //     without drawing down the shared one, so it cannot starve everybody else on its way
+    //     to being refused. Neither refusal names its ceiling: a published number is a
+    //     calibration table telling a flood exactly how many keys to mint.
+    if (signedAccountRate && !signedAccountRate.allow(account)) {
+      return rpcError(reqId, ERRORS.RATE_LIMITED,
+        'you are sending faster than this door answers — slow down and retry');
+    }
+    if (signedTotalRate && !signedTotalRate.allow()) {
+      return rpcError(reqId, ERRORS.RATE_LIMITED,
+        'this entry is at its ceiling right now — retry shortly');
+    }
+
     noteContact(account);
     // T107: `wba_did` may legitimately differ from `peer_did` (the transport signer vs
     // the message signer) — both facts are honest, and the schema says which is which.
@@ -2493,6 +2922,44 @@ export function createAgentEntry({
     return pathname === mount || pathname === `${mount}/`;
   }
 
+  /** The GET routes this entry owns, built ONCE from the mount so a request path is a
+   *  lookup and never string arithmetic. On a GUEST mount the card is served at the
+   *  ORIGIN's well-known paths TOO — that is the only address a stranger's agent knows to
+   *  try (RFC 8615), and a door nobody can find is not a door. The card's `url` still names
+   *  the DOOR, which is ordinary A2A: the well-known location is where a card is
+   *  DISCOVERED, not the endpoint it describes. */
+  const CARD_ROUTES = new Set([mount + AGENT_CARD_PATH, mount + AGENT_CARD_PATH_LEGACY]);
+  const SIG_ROUTES = new Set([mount + AGENT_CARD_SIG_PATH]);
+  if (guestMount) {
+    CARD_ROUTES.add(AGENT_CARD_PATH).add(AGENT_CARD_PATH_LEGACY);
+    SIG_ROUTES.add(AGENT_CARD_SIG_PATH);
+  }
+
+  /** What `Allow:` may truthfully say about THIS path, or null when the entry does not own
+   *  it at all. RFC 9110 §10.2.1 makes `Allow` a statement about the target RESOURCE, so a
+   *  single server-wide list is a wrong answer to a right question — and on a guest mount
+   *  it would be worse than wrong: answering for `/` at all, even with a 204 and a header,
+   *  is speaking for the site's own front page, which is the one thing a guest mount must
+   *  never do. Whatever the GET route does for an address we do not own (404), OPTIONS and
+   *  the method table do the same. */
+  function allowFor(pathname) {
+    if (CARD_ROUTES.has(pathname) || SIG_ROUTES.has(pathname)) return ALLOW_CARD;
+    if (isMountPath(pathname)) return guestMount ? ALLOW_DOOR : ALLOW_MOUNT;
+    return null;
+  }
+
+  /** The headers that state a resource's methods — BOTH spellings, always the same value.
+   *  `Allow` and `Access-Control-Allow-Methods` answer the same question for two different
+   *  readers, and a response that says `Allow: POST, OPTIONS` beside
+   *  `Access-Control-Allow-Methods: GET, POST, OPTIONS` contradicts itself in one message:
+   *  a browser-resident agent preflighting the guest door was told GET was on the menu at
+   *  the exact address whose GET is 405. `CORS_HEADERS` stays the origin-wide default
+   *  everywhere else (a card GET, a signed reply, a 404); it is narrowed only where the
+   *  resource's real method list is known, which is exactly where `Allow` is emitted. */
+  function allowHeaders(allow) {
+    return { Allow: allow, 'Access-Control-Allow-Methods': allow };
+  }
+
   function route(method, path, bodyBuffer, headers) {
     // Classified ONCE per request, used only to count and to signpost. Everything the
     // ladder decides is decided exactly as if this line did not exist.
@@ -2514,21 +2981,27 @@ export function createAgentEntry({
     // 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 === mount + AGENT_CARD_PATH || pathname === mount + AGENT_CARD_PATH_LEGACY) {
-        // Byte-identical on both paths: the current A2A path and the legacy alias.
+      if (CARD_ROUTES.has(pathname)) {
+        // Byte-identical on every path: the current A2A path, the legacy alias, and (on a
+        // guest mount) the origin's well-known copy of both. Which address a client
+        // happened to fetch must never change what it believes about this DID.
         tally(family, 'card_get');
         // T107: identify (count), never enrol, never change a byte. Runs only after a
         // route MATCHED, so refused/404 paths never pay for crypto.
         wbaObserve(headers);
         return { status: 200, headers: cardHeaders(cardBytes.length), body: cardBytes };
       }
-      if (pathname === mount + AGENT_CARD_SIG_PATH) {
+      if (SIG_ROUTES.has(pathname)) {
         const env = cardEnvelopeBytes();
         tally(family, 'card_get');
         wbaObserve(headers);
         return { status: 200, headers: cardHeaders(env.length), body: env };
       }
-      if (isMountPath(pathname)) {
+      // The human notice — NOT served on a guest mount, where GET belongs to the site (E3).
+      // Falling through to 404 is deliberate and is the same non-disclosure the POST route
+      // already makes: an entry beside other agents does not confirm what lives at an
+      // address it was not given.
+      if (!guestMount && isMountPath(pathname)) {
         tally(family, 'notice_get');
         wbaObserve(headers);
         const body = Buffer.from(
@@ -2547,6 +3020,22 @@ export function createAgentEntry({
             ...steerHeaders(family) },
           body };
       }
+      // A GUEST MOUNT'S DOOR ANSWERS GET WITH 405, NOT 404 (proof run 3, 2026-08-18).
+      // Run A guessed the door path CORRECTLY, GET it, and was told nothing was there —
+      // its one correct guess, refuted. This is NOT the
+      // DECISION(non-door-post-answers-404-not-405) non-disclosure case, and the
+      // difference is where the address came from: that decision protects a path a caller
+      // GUESSED AT RANDOM, where a 405 would confirm a door it has no right to know about.
+      // The door's address is PUBLISHED, in the card, signed, at a well-known path — so
+      // hiding it from a GET conceals nothing from anyone and costs a visitor the one
+      // thing it got right. `allowFor` is non-null here only for the guest door: card and
+      // signature routes matched above, and a site-owning mount already returned its
+      // notice. A path this entry does not own still falls through to 404, and a guest
+      // mount still answers nothing it does not own.
+      const getAllow = allowFor(pathname);
+      if (getAllow !== null) {
+        return jsonResponse(405, { error: 'method not allowed' }, allowHeaders(getAllow));
+      }
       return jsonResponse(404, { error: 'not found' });
     }
     if (method === 'POST') {
@@ -2564,12 +3053,23 @@ export function createAgentEntry({
       tally(family, postStage(buf, out));
       return out;
     }
+    // Everything below answers for a RESOURCE, so an address this entry does not own is a
+    // 404 first — the same answer GET and POST give it. Before this, OPTIONS 204'd for
+    // EVERY path (a guest mount would have spoken for the site's front page one verb over)
+    // and the 405 carried no `Allow` at all, which RFC 9110 §15.5.6 REQUIRES.
+    const allow = allowFor(pathname);
+    if (allow === null) return jsonResponse(404, { error: 'not found' });
     if (method === 'OPTIONS') {
+      // The CORS PREFLIGHT lands here: a browser-resident agent POSTing application/json
+      // is not a simple request, so this answer is what decides whether the POST is ever
+      // sent. BOTH method statements narrow to the resource: `Allow` and
+      // `Access-Control-Allow-Methods` are the same fact for two readers, and this is the
+      // one response where the browser reader acts on it.
       return { status: 204,
-        headers: { Allow: 'GET, POST, OPTIONS', 'Content-Length': '0', ...CORS_HEADERS },
+        headers: { 'Content-Length': '0', ...CORS_HEADERS, ...allowHeaders(allow) },
         body: Buffer.alloc(0) };
     }
-    return jsonResponse(405, { error: 'method not allowed' });
+    return jsonResponse(405, { error: 'method not allowed' }, allowHeaders(allow));
   }
 
   function cardHeaders(length) {