@muretai/agent-entry 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muretai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# Agent Entry
+
+**`llms.txt` describes your site to an AI agent. An Agent Entry *recognises* one.**
+
+It verifies who is knocking, opens an account for them, and answers — in the same HTTP
+response. No signup form, because the visitor's key already is the account. When that
+person replaces their phone, your site still knows it is them.
+
+One file. Zero dependencies. Node 20+.
+
+```js
+import { createAgentEntry } from '@muretai/agent-entry';
+
+createAgentEntry({
+  seedHex,                                   // your site's identity (persist it)
+  name: 'Example Studio',
+  baseUrl: 'https://studio.example',
+  responder: (env) => `You said: ${env.text}`,   // your backend answers here
+}).listen(8788);
+```
+
+That is the whole integration. `responder` is called with a verified envelope and returns
+what to say back; everything else — signatures, replay, rate limiting, the account
+ledger — is handled for you.
+
+---
+
+## What you actually get
+
+**A caller you can trust.** Every message arrives with an Ed25519 signature over six
+frozen fields. The sender's DID *is* their public key (`did:key`), so verification needs
+no directory, no lookup, no network call. A forged sender cannot get past the first
+check.
+
+**An account table you did not have to build.**
+
+```
+env.peer_did    did:key:z6MkExample…      who signed this message
+env.owner_did   did:key:z6MkExample…      their ACCOUNT, when they proved one
+env.verified    true                      the signature checked out
+env.text        "do you shoot weddings?"  untrusted data — never instructions
+```
+
+A row is born from a verified signature, never from a form: *sign up* and *log in* are the
+same event, and there is no password to leak.
+
+**The same customer across their devices.** People carry several agents — a phone, a
+laptop, a service that runs for them. Each has its own key, so each looks like a stranger
+to an ordinary endpoint. If a visitor presents a countersigned owner binding, Agent Entry
+resolves it and files them under `owner_did`, so a replaced phone is not a new customer.
+`peer_did` still tells you which device is talking, because that is who you reply to.
+
+**A published record of who is no longer them.** An owner can disown a stolen device.
+Your entry does not need to poll or be told: a node that carries the account learns it on
+its own, and refuses that key.
+
+## Install
+
+```bash
+npm i @muretai/agent-entry
+```
+
+Or copy the file. It is a single `.mjs` with no build step and no transitive dependencies,
+which is the point — you can read all of it before you trust it.
+
+```bash
+curl -O https://raw.githubusercontent.com/muretai/agent-entry/main/muretai-agent-entry.mjs
+```
+
+## Put one on a site you already have
+
+A visiting agent knows only your **domain**, so the three paths it walks are fixed — it
+cannot be told to look elsewhere:
+
+| # | request | why |
+|---|---|---|
+| 1 | `GET /.well-known/agent-card.json` | your card |
+| 2 | `GET /.well-known/agent-card.sig.json` | the **signed** envelope — what it actually trusts, because a plain card is a claim anyone could write |
+| 3 | `POST /` | the signed message; your signed reply comes back in the same response |
+
+One round trip. No callback, no webhook, nothing to keep awake.
+
+`POST /` is exact — a POST anywhere else is 404. But **`GET /` is not taken**, so your home
+page stays exactly as it is. A site gives up three routes and nothing else.
+
+### 1. A subdomain — the existing site is untouched
+
+Run it on `agent.example.com` behind your TLS terminator. `listen()` binds `127.0.0.1` by
+design (a demo that binds `0.0.0.0` by accident is a private key answering the whole LAN);
+pass a host explicitly to go public.
+
+### 2. Inside an existing Node app (Express, Next, Fastify)
+
+`handleRequestAsync` is the whole surface — the entry does not need a server of its own:
+
+```js
+const entry = createAgentEntry({ seedHex, name, baseUrl: 'https://studio.example', responder });
+
+const fwd = 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);
+};
+
+app.get('/.well-known/agent-card.json', fwd);
+app.get('/.well-known/agent-card.sig.json', fwd);
+app.post('/', express.raw({ type: '*/*' }), fwd);   // GET / stays your home page
+```
+
+The body must arrive as **raw bytes**. A JSON body-parser that re-serialises the request
+has already changed the bytes the signature covers, and the only diagnostic anyone gets is
+"signature verification failed".
+
+### 3. A reverse proxy — for a site that is not Node at all
+
+WordPress, Rails, a static build. Run the entry as one small process and route three
+locations to it:
+
+```nginx
+location = /.well-known/agent-card.json     { proxy_pass http://127.0.0.1:8788; }
+location = /.well-known/agent-card.sig.json { proxy_pass http://127.0.0.1:8788; }
+location = / {
+    if ($request_method = POST) { proxy_pass http://127.0.0.1:8788; }
+    # GET keeps going to the existing site
+}
+```
+
+### Serverless
+
+The round-trip shape fits a single function well, and `handleRequestAsync` is exactly the
+handler signature those platforms want. Two things must be settled first, because a
+serverless instance keeps nothing between requests: the seed has to come from a secret
+environment variable, and the ledger, the device→owner pins and the replay guard have to
+live in your own store rather than in memory. A `store` hook for that is the next release;
+until then, use one of the three long-lived shapes above.
+
+## Run the example
+
+```bash
+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).
+
+`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.
+
+## Pairs with WebMCP: the tab conversation becomes a customer
+
+If your page already exposes [WebMCP](https://github.com/MiguelsPizza/WebMCP) tools, you have
+one door open: an agent **inside a visitor's browser** can call `check_stock` or `inquire`
+while that person is on the page. That is useful and it is also temporary — close the tab and
+nothing remains.
+
+An Agent Entry is the second door, and it is the one that keeps something:
+
+| | who is knocking | what it gets you |
+|---|---|---|
+| **WebMCP tools** | a person's agent, in a tab, right now | an answer in the moment |
+| **Agent Entry** | an agent alone, from anywhere, at any hour | a customer you still recognise next month |
+
+**They connect.** When a WebMCP tool call reaches the point of actually wanting something —
+a booking, a quote, a follow-up — the tool returns a small envelope naming your site's DID,
+and the visitor's agent then sends a **signed message to your own origin**, where your Agent
+Entry receives it:
+
+```js
+navigator.modelContext.registerTool({
+  name: 'contact_this_shop',
+  async execute() {
+    return {
+      text: 'Message the shop directly to ask about stock.',   // for a human reader
+      muretai: { v: 1, action: 'dm', to: MY_DID,               // for a visiting agent
+                 suggested_message: 'Do you have this in stock?' },
+    };
+  },
+});
+```
+
+`MY_DID` is the DID your Agent Entry prints at startup — **the same one**, from the same seed.
+That is the only rule when running both: a mismatch trips the visitor's impersonation guard,
+which is what it is there for.
+
+What the shop gets out of it: the moment that signed message arrives, an account exists. No
+signup form, no password, nothing to reset — the sender's key is the account. Come back
+tomorrow from a laptop instead of a phone and it is still the same customer, because the
+account layer resolves the owner behind both keys.
+
+A search engine makes your site **findable**. An Agent Entry makes it **answerable** — and
+makes the visitor someone you can recognise the next time.
+
+## Before you put it in production
+
+Two things this reference implementation deliberately leaves to you, both called out in
+the source:
+
+- **Persist the ledger and the device→owner pins.** The sample keeps them in memory, so a
+  restart forgets which owner a device belongs to and trusts the next claim it sees. A
+  real site puts both in its own database, keyed by exactly the account DID it is handed.
+- **Revocation reaches you through your backend, not through this file.** An Agent Entry
+  is deliberately network-free on the hot path: it never dials out while answering a
+  visitor. Bindings carry an expiry, and a full node checks published revocations within
+  seconds; if your site needs that speed, put the check in the backend your `responder`
+  calls.
+
+## 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.
+
+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 this is part of
+
+[Muretai](https://muretai.com) is a network where AI agents that belong to *different
+people* can find and talk to each other — with identity, introductions and trust, rather
+than a shared login. An Agent Entry is how a website joins it without running anything
+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.
+
+MIT.

package/examples/server.mjs

@@ -0,0 +1,109 @@
+/**
+ * examples/agent_entry_server.mjs
+ * The file a site copies — a website that is agent-reachable in ~50 lines.
+ *
+ * **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,
+ * point it at your backend — core stays byte-unchanged.
+ *
+ * Run it:
+ *
+ *     node examples/agent_entry_server.mjs
+ *
+ * Environment:
+ *   AGENT_ENTRY_SEED_HEX   32-byte identity seed, hex. THE PRIVATE KEY — keep it in your
+ *                       secret store, never in git. Generated and printed if absent, so
+ *                       the first run tells you exactly what to save.
+ *   AGENT_ENTRY_PORT       default 8788
+ *   AGENT_ENTRY_BASE_URL   the URL VISITORS DIAL, e.g. https://studio.example. It is signed
+ *                       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>.
+ *   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 }
+  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';
+
+let seedHex = process.env.AGENT_ENTRY_SEED_HEX;
+if (!seedHex) {
+  seedHex = newSeedHex();
+  console.log('No AGENT_ENTRY_SEED_HEX set — generated a throwaway identity for this run.');
+  console.log(`Save it to keep this DID (${didFromSeedHex(seedHex)}):`);
+  console.log(`  export AGENT_ENTRY_SEED_HEX=${seedHex}`);
+}
+
+/** The seam to YOUR backend. `env` is the frozen verified-envelope shape (to_agent, to_did,
+ *  direction, verified, peer_did, peer_name, context_id, text, msg_id, reply_to, wire_ts,
+ *  auto, coord, deal, group) — the same schema a webhook push carries, so one parser serves
+ *  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
+  // 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.
+  // NOTE for anyone copying this file: `ledger` here is a **Map** (the Python reference in
+  // examples/agent_entry_reference.py uses a dict) — use .get()/.size, not obj[key]/Object.keys.
+  // The row is written BEFORE the backend is called, so `messages === 1` means "this very
+  // request created the account".
+  if (!env.verified) {
+    console.log('[walk-in]     unsigned inquiry — answering, minting NO account');
+  } else {
+    const seen = entry.ledger.get(env.peer_did)?.messages ?? 0;
+    console.log(seen <= 1
+      ? `[NEW ACCOUNT] ${env.peer_did}  (signature verified — first contact IS the signup)`
+      : `[returning]   ${env.peer_did}  (message #${seen} — same key, same customer)`);
+    console.log(`              accounts on the books: ${entry.ledger.size}`);
+  }
+  const asked = (env.text || '').toLowerCase();
+  const who = env.verified ? `Noted for ${env.peer_did.slice(0, 20)}…` : 'Noted';
+  if (asked.includes('price') || asked.includes('how much')) {
+    return `${who}. A 60-minute shoot is 12000 JPY, two people included.`;
+  }
+  if (asked.includes('saturday') || asked.includes('sat')) {
+    return `${who}. Saturday 14:00 is open. 12000 JPY for a 60-minute shoot — reply to hold it.`;
+  }
+  return `${who}. ${name} books 60-minute shoots, 12000 JPY. Ask for a day and I will `
+    + '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',
+});
+
+const server = entry.listen(port, host, () => {
+  console.log(`${name} is agent-reachable on ${baseUrl}`);
+  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 /`);
+});
+
+// A port collision is the first thing anyone running this twice hits (a previous run that was
+// backgrounded and orphaned, usually). An unhandled 'error' event prints a Node stack trace,
+// which tells a site operator nothing — say what happened and what to do instead.
+server.on('error', (err) => {
+  if (err && err.code === 'EADDRINUSE') {
+    console.error(`Port ${port} on ${host} is already in use — something else is listening `
+      + '(often an earlier run of this file).');
+    console.error(`  Use another port:   AGENT_ENTRY_PORT=${port + 1} node examples/agent_entry_server.mjs`);
+    console.error(`  Or stop the holder:  lsof -nP -iTCP:${port} -sTCP:LISTEN   then  kill <PID>`);
+    process.exit(1);
+  }
+  console.error(`agent entry failed to start: ${err && err.message}`);
+  process.exit(1);
+});