@muretai/agent-entry 1.9.0 → 1.10.0

package/README.md

@@ -105,6 +105,7 @@ answers questions and hands off nothing, is a signed claim you cannot keep.
 |---|---|---|
 | `skills` | `[]` | the menu above — what a visitor learns before knocking |
 | `openDoor` | `true` | publishes `agentEntry.open_door`: the field that tells a visiting agent it may message you with no introduction. The same fact is emitted under the older `muretai.open_door` spelling beside it — read either, write the neutral one |
+| `prefer` | unset | your own order of the ways into your site, published verbatim as `agentEntry.prefer` (spec AE-30): an array of `"page"`, `"card"`, `"mcp"` or `{kind, when}` with `when` one of `person`, `alone`, `key`, `no-key`, `token`, `browser` — e.g. `[{kind:'page', when:'no-key'}, 'card']` says "read on the page if you hold no key; otherwise the door". A visiting agent reads it against what it has on hand. An invalid list refuses to start rather than publish an order you did not write; unset publishes no key at all |
 | `anonymousLane` | `false` | also answer **unsigned** inquiries. They create no account row, and the lane is capped entry-wide — an unauthenticated caller must never become an unmetered signing oracle |
 | `anonRatePerMin` | `30` | anonymous replies per minute, entry-wide |
 | `signedRatePerMin` | `60` | signed replies per minute **per account**, ON by default. Attribution is not scarcity: a `did:key` costs nothing to mint, so being in your ledger was never a bound |
@@ -381,7 +382,8 @@ node examples/server.mjs        # prints its DID and card URL
 Environment: `AGENT_ENTRY_SEED_HEX` (generated and printed if absent — **persist it, it is
 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).
+no account), `AGENT_ENTRY_PREFER` (your order of the ways in, as one JSON array — see
+`prefer` above; an invalid list refuses to start).
 
 ## What `baseUrl` may be
 

package/examples/server.mjs

@@ -43,6 +43,10 @@
  *                       https://example.com/agent) and answers NOTHING at `/` — no notice,
  *                       no OPTIONS, no POST. Point your proxy at the door path and the
  *                       well-known paths; the site keeps everything else, unchanged.
+ *   AGENT_ENTRY_PREFER     OPTIONAL: the site's own order of its ways in, as one JSON array
+ *                       (AE-30), e.g. '[{"kind":"page","when":"no-key"},"card"]' — "read on
+ *                       the page if you hold no key; otherwise the door". Published verbatim
+ *                       as `agentEntry.prefer`; an invalid list REFUSES to start.
  *   AGENT_ENTRY_WBA_JWKS   OPTIONAL: a JWKS document {"keys":[…]} as one JSON string —
  *                       the Web Bot Auth key directory (verified out of band) whose
  *                       holders this entry should RECOGNISE on inbound requests. Off
@@ -156,6 +160,10 @@ try {
     ...(process.env.AGENT_ENTRY_SIGNED_RATE_TOTAL
       ? { signedRatePerMinTotal: Number(process.env.AGENT_ENTRY_SIGNED_RATE_TOTAL) } : {}),
     guest: process.env.AGENT_ENTRY_GUEST === '1',
+    // AE-30: the site's own order of its ways in, a JSON array. Malformed JSON or an
+    // unknown kind/condition throws inside this try and the entry never starts — the same
+    // posture as a bad domain list: never publish a statement the operator did not make.
+    ...(process.env.AGENT_ENTRY_PREFER ? { prefer: JSON.parse(process.env.AGENT_ENTRY_PREFER) } : {}),
     wbaVerifiers,
   });
 } catch (err) {

package/muretai-agent-entry.mjs

@@ -2148,6 +2148,43 @@ function domainFix(candidate) {
  * refuses every other bad value there. Truncating would start the entry with a claim that
  * is USABLE and NOT WHAT THEY SAID.
  */
+/** The kinds a visitor can take into a site, and the conditions a site may attach. Kept
+ *  identical to the visitor side (Agent Web Router `parsePrefer`): a kind or condition one
+ *  side knows and the other does not is a declaration one side silently drops. */
+export const PREFER_KINDS = ['page', 'card', 'mcp'];
+export const PREFER_WHEN = ['person', 'alone', 'key', 'no-key', 'token', 'browser'];
+
+/**
+ * The exact `agentEntry.prefer` this entry may publish, or a TypeError (AE-30).
+ *
+ * The site's own order of its ways in — "read on the page if you have no key, then the
+ * door", say. VALIDATED, NEVER REWRITTEN: this goes on a SIGNED card, and a card that says
+ * something the operator did not write is a worse card than none, so an unknown kind, an
+ * unknown condition or a stray key refuses the whole declaration instead of trimming it —
+ * the same posture as `canonicalDomains`. `null`/`undefined` means "not configured", and
+ * then no `prefer` key is published at all, which is what keeps an already-deployed
+ * entry's bytes unchanged.
+ */
+export function validatePrefer(prefer) {
+  if (prefer == null) return null;
+  if (!Array.isArray(prefer) || prefer.length === 0) {
+    throw new TypeError('agentEntry.prefer must be a non-empty array of "page" | "card" | "mcp" or {kind, when}');
+  }
+  for (const e of prefer) {
+    if (typeof e === 'string') {
+      if (!PREFER_KINDS.includes(e)) throw new TypeError(`agentEntry.prefer: unknown kind ${JSON.stringify(e)}`);
+      continue;
+    }
+    if (!e || typeof e !== 'object' || Array.isArray(e)) throw new TypeError('agentEntry.prefer: an entry must be a kind or {kind, when}');
+    const keys = Object.keys(e);
+    if (!PREFER_KINDS.includes(e.kind)) throw new TypeError(`agentEntry.prefer: unknown kind ${JSON.stringify(e.kind)}`);
+    if ('when' in e && !PREFER_WHEN.includes(e.when)) throw new TypeError(`agentEntry.prefer: unknown condition ${JSON.stringify(e.when)}`);
+    const stray = keys.filter((k) => k !== 'kind' && k !== 'when');
+    if (stray.length) throw new TypeError(`agentEntry.prefer: unexpected key(s) ${stray.join(', ')}`);
+  }
+  return prefer;
+}
+
 export function canonicalDomains(domains, { warn = true } = {}) {
   if (domains === undefined || domains === null) return [];
   if (!Array.isArray(domains)) {
@@ -2269,6 +2306,11 @@ export function canonicalMount(canonUrl, basePath) {
  *   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.
+ *   prefer         OPTIONAL: the site's own order of its ways in, published as
+ *                  `agentEntry.prefer` (AE-30) — e.g. `[{kind:'page', when:'no-key'}, 'card']`
+ *                  says "read on the page if you hold no key; otherwise the door". Validated
+ *                  by `validatePrefer`; an invalid list throws, so the entry never starts
+ *                  with a statement the operator did not make. Absent = no key published.
  *   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
@@ -2330,6 +2372,7 @@ export function createAgentEntry({
   version = '1',
   responder = () => 'Thanks — a human will follow up.',
   openDoor = true,
+  prefer = null,
   anonymousLane = false,
   anonRatePerMin = ANON_RATE_PER_MIN,
   signedRatePerMin = SIGNED_RATE_PER_MIN,
@@ -2404,7 +2447,10 @@ export function createAgentEntry({
   // 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 };
+  // AE-30: the site's order rides on the NEUTRAL key only; the alias stays `open_door`
+  // alone, so an old consumer that compares the two aliases byte for byte keeps passing.
+  const canonPrefer = validatePrefer(prefer);
+  if (openDoor) card.agentEntry = { open_door: true, ...(canonPrefer ? { prefer: canonPrefer } : {}) };
   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

package/package.json

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

package/spec/v1.md

@@ -396,6 +396,25 @@ higher rate than the signed lane's aggregate.
 > **Observation.** With the lane on, drive unsigned requests above the bound; assert refusal. An
 > unauthenticated caller must never become an unmetered signing oracle.
 
+**AE-30.** An entry **MAY** publish `agentEntry.prefer`: the site's own order of its ways in
+for a visiting agent. It is an array whose entries are a kind — `"page"`, `"card"`, `"mcp"` —
+or an object `{"kind": <kind>, "when": <condition>}` with `when` one of `person`, `alone`,
+`key`, `no-key`, `token`, `browser`, read by the visitor against what it has on hand. When
+published it **MUST** appear under the neutral `agentEntry` key exactly as the operator
+declared it (validated, not rewritten), and **MUST** appear identically in the signed
+envelope's inner card. The legacy `muretai` alias **MUST NOT** carry it. When not configured,
+the card **MUST NOT** carry a `prefer` key. A declaration that fails validation **MUST** make
+the entry refuse to start rather than publish a corrected or partial order.
+
+> **Observation.** Start an entry with a declaration; `GET` the card and the envelope; assert
+> `agentEntry.prefer` equals the declaration in both and `muretai` has no `prefer`. Start one
+> without; assert no `prefer` key. Start one with `["teleport"]`; assert it exits non-zero and
+> binds nothing. Why refuse rather than fix: a signed card is the origin's statement, and a
+> statement the operator did not make is a worse card than none — the same posture as a bad
+> `domains` list. Why the visitor's conditions live here: which way in a stranger should try
+> first is the site's design (read on the page, become a counterparty later — or knock first),
+> and the card is the one place the site can say so that a page script cannot rewrite.
+
 ---
 
 ## 5. Relationship to other specifications
@@ -629,6 +648,7 @@ be written is a requirement that does not belong in §4.
 | AE-27 | MUST | size caps | oversized body and text |
 | AE-28 | MUST | aggregate reply ceiling, refused with `-32004` | drive above the ceiling |
 | AE-29 | MUST | unsigned lane bounded entry-wide | drive the anonymous lane |
+| AE-30 | MAY / MUST | `agentEntry.prefer` verbatim on card + envelope, or absent; invalid refuses to start | `GET` both, compare; start with a bad list → exit ≠ 0 |
 
 ---