@muretai/agent-entry 1.9.0 → 1.11.0

package/diagrams/desk.svg

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 740 300" role="img">
+  <title>Keep WebMCP. Add a door beside it if the agent is alone.</title>
+  <rect width="740" height="300" fill="#fafafa"/>
+  <text x="24" y="26" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" fill="#666">A person in the tab keeps WebMCP. An agent alone can become a customer at the door beside it.</text>
+  <rect x="20" y="44" width="340" height="140" rx="10" fill="#111"/>
+  <text x="190" y="80" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="15" font-weight="700" fill="#fff">A person is in the tab</text>
+  <text x="190" y="114" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#ddd">Keep WebMCP</text>
+  <text x="190" y="144" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#bbb">the page is theirs</text>
+  <rect x="380" y="44" width="340" height="140" rx="10" fill="#fff" stroke="#111"/>
+  <text x="550" y="80" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="15" font-weight="700" fill="#111">The agent is alone</text>
+  <text x="550" y="114" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#555">Add a door beside WebMCP</text>
+  <text x="550" y="144" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#111">they can become a customer</text>
+  <rect x="20" y="200" width="700" height="80" rx="10" fill="#fff" stroke="#111"/>
+  <text x="370" y="232" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="14" font-weight="700" fill="#111">GET /.well-known/agent-card.json  200</text>
+  <text x="370" y="260" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="14" font-weight="700" fill="#111">POST /  message/send  200  signed reply</text>
+</svg>

package/diagrams/x402.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 740 280" role="img" aria-labelledby="t d">
+  <title id="t">x402 teaches with HTTP 402; Agent Entry teaches on GET 200</title>
+  <desc id="d">x402: request the resource, receive HTTP 402 and PAYMENT-REQUIRED, retry with PAYMENT-SIGNATURE. Agent Entry: GET the Agent Card as 200 before the knock, then POST already correct, answered 200. A refusal is JSON-RPC on HTTP 200, not HTTP 402.</desc>
+  <rect width="740" height="280" fill="#fafafa"/>
+  <rect x="20" y="20" width="340" height="240" rx="10" fill="#fff" stroke="#111"/>
+  <text x="190" y="48" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="15" font-weight="700" fill="#111">x402 (HTTP)</text>
+  <text x="190" y="80" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#333">1. ask for the resource</text>
+  <text x="190" y="108" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#333">2. HTTP 402 + PAYMENT-REQUIRED</text>
+  <text x="190" y="136" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#333">3. retry with PAYMENT-SIGNATURE</text>
+  <text x="190" y="164" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#333">4. 200 if paid</text>
+  <text x="190" y="204" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" fill="#666">The error is how the client learns</text>
+  <text x="190" y="224" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" fill="#666">what to do next.</text>
+  <rect x="380" y="20" width="340" height="240" rx="10" fill="#111"/>
+  <text x="550" y="48" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="15" font-weight="700" fill="#fff">Agent Entry</text>
+  <text x="550" y="80" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#fff">1. GET agent-card.json  (200)</text>
+  <text x="550" y="108" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#fff">2. read how to sign (AE-8)</text>
+  <text x="550" y="136" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#fff">3. POST message/send  (200)</text>
+  <text x="550" y="164" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="13" fill="#fff">4. signed reply, same request</text>
+  <text x="550" y="204" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" fill="#ddd">The POST is not a retry after an error.</text>
+  <text x="550" y="224" text-anchor="middle" font-family="ui-sans-serif, system-ui, sans-serif" font-size="12" fill="#ddd">A refusal is JSON-RPC on HTTP 200.</text>
+</svg>

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

@@ -761,7 +761,7 @@ export function signEnvelope(seedHex, fields) {
 /** Question 1 ONLY: does `sig` verify under the key DERIVED FROM `from`, over the six
  *  fields? Total and fail-closed — a malformed DID, bad base64, unrenderable number or
  *  short signature all answer false rather than throwing. */
-export function verifyEnvelopeSignature(fields) {
+export function verifyEnvelopeSignature(fields, opts = {}) {
   try {
     if (!fields || typeof fields !== 'object') return false;
     // `from` (the key) and `sig` must be there; `to` may be the EMPTY STRING — that is how
@@ -772,7 +772,11 @@ export function verifyEnvelopeSignature(fields) {
     assertEncodable(payload);
     const sig = Buffer.from(String(fields.sig), 'base64');
     if (sig.length !== 64) return false;
-    return verifyBytes(publicKeyFromDid(fields.from), sig, Buffer.from(payload, 'utf8'));
+    // Payload `from` stays the root DID. `signerDid` is the verifying key when the
+    // sender enrolled a delegated op-key (T142 A2); omitted → `from` (the un-enrolled
+    // / this-door-reply case).
+    const signerDid = opts.signerDid || fields.from;
+    return verifyBytes(publicKeyFromDid(signerDid), sig, Buffer.from(payload, 'utf8'));
   } catch {
     return false;
   }
@@ -805,12 +809,82 @@ export function verifyEnvelope(fields, opts = {}) {
     const recipient = opts.recipientDid ?? opts.me ?? fields.recipientDid ?? null;
     if (typeof recipient !== 'string' || !recipient) return false;
     if (fields.to !== recipient) return false;
-    return verifyEnvelopeSignature(fields);
+    return verifyEnvelopeSignature(fields, opts);
   } catch {
     return false;
   }
 }
 
+// ================================================================ KeyState (inline op-key, T142 A2)
+//
+// A persisted muretai identity enrolls a genesis KeyState at birth and signs
+// messages with a delegated op-key while `from` stays the root DID. This door
+// used to verify under `from` only, which refused every default-enrolled
+// visitor. Resolve the op-key from a valid inline KeyState (root-signed, pin
+// to the claimed `from`); a missing or invalid record falls back to `from`.
+// No directory, no pin store — first-contact, same as the Python twin.
+
+const KEYSTATE_TYP = 'muretai/keystate/1';
+// Lockstep with shared/keystate._FIELDS_V1 / _signed_names: presence of
+// encPubPqHash (even "") selects the T142 list. A V1-only list made every
+// default-enrolled visitor fail verify and fall back to the root DID, so
+// the op-signed envelope was -32001 at this door only (Python twin accepted).
+const KEYSTATE_FIELDS_V1 = [
+  'typ', 'rootDid', 'epoch', 'rootKey', 'rootNextHash',
+  'opDid', 'opNextHash', 'encPub', 'encNextHash',
+  'guardiansHash', 'revokedOps', 'notBefore', 'notAfter', 'ts',
+];
+function keystateSignedNames(ks) {
+  if (ks && Object.prototype.hasOwnProperty.call(ks, 'encPubPqHash')) {
+    return KEYSTATE_FIELDS_V1.concat(['encPubPqHash']);
+  }
+  return KEYSTATE_FIELDS_V1;
+}
+const MAX_KEYSTATE_EPOCH = 2147483647; // 2**31 - 1, shared/keystate.MAX_EPOCH
+
+export function verifyKeystate(ks, expectedRootDid, now) {
+  try {
+    if (!ks || typeof ks !== 'object') return false;
+    if (ks.typ !== KEYSTATE_TYP) return false;
+    const rootDid = ks.rootDid;
+    const epoch = ks.epoch;
+    if (!Number.isInteger(epoch) || epoch < 0 || epoch > MAX_KEYSTATE_EPOCH) return false;
+    if (expectedRootDid != null && rootDid !== expectedRootDid) return false;
+    const didKey = publicKeyHexFromDid(rootDid);
+    if (ks.rootKey !== didKey) return false;
+    const sig = Buffer.from(String(ks.sig), 'base64');
+    if (sig.length !== 64) return false;
+    const payloadObj = {};
+    for (const k of keystateSignedNames(ks)) {
+      payloadObj[k] = ks[k] === undefined ? null : ks[k];
+    }
+    const payload = canonicalJSON(payloadObj);
+    const pub = Buffer.from(String(ks.rootKey), 'hex');
+    if (pub.length !== 32) return false;
+    if (!verifyBytes(pub, sig, Buffer.from(payload, 'utf8'))) return false;
+    if (now != null) {
+      const nb = ks.notBefore || 0;
+      const na = ks.notAfter;
+      if (now < nb) return false;
+      if (na != null && now > na) return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveOpDid(rootDid, inlineKeystate, now) {
+  if (inlineKeystate && verifyKeystate(inlineKeystate, rootDid, now)) {
+    const burned = Array.isArray(inlineKeystate.revokedOps)
+      ? inlineKeystate.revokedOps : [];
+    const op = inlineKeystate.opDid || rootDid;
+    if (burned.includes(op)) return rootDid;
+    return op;
+  }
+  return rootDid;
+}
+
 // ================================================================ Web Bot Auth (RFC 9421 subset, verify-only) — T107
 //
 // The INBOUND half only: did the holder of one of the keys this entry was GIVEN sign
@@ -1770,6 +1844,43 @@ function isThenable(v) {
   return v !== null && typeof v === 'object' && typeof v.then === 'function';
 }
 
+/**
+ * `then1(x, f)` — apply `f` to `x`, awaiting `x` only if it is a promise.
+ *
+ * This is what lets ONE verification ladder serve both the synchronous in-memory state and
+ * an asynchronous external `store` (T105), instead of the ladder being written twice and
+ * drifting. Writing it twice was the alternative considered and rejected: the ladder is the
+ * security-critical path, its steps are ORDER-DEPENDENT, and two copies of an ordered
+ * security argument is how one of them silently stops matching the other.
+ *
+ * The sync branch is not an optimisation — it is the contract. With no store, every step
+ * returns a plain value, the ladder returns a plain value, and `handleRequest` (the
+ * synchronous entry point) keeps working exactly as it always has.
+ */
+function then1(x, f) {
+  return isThenable(x) ? x.then(f) : f(x);
+}
+
+/**
+ * Validate a caller-supplied `store` and return it unchanged.
+ *
+ * Checked ONCE at construction rather than per call, and it throws rather than filling in a
+ * default: a store missing `seenMessage` would otherwise silently disable replay protection,
+ * and the failure would appear as "the door works" until somebody replayed a message.
+ */
+function asStore(store) {
+  const REQUIRED = ['seenMessage', 'getAccount', 'putAccount', 'getDeviceOwner',
+    'putDeviceOwner'];
+  const missing = REQUIRED.filter((m) => typeof store[m] !== 'function');
+  if (missing.length) {
+    throw new TypeError(
+      `createAgentEntry: store is missing ${missing.join(', ')}. A store must implement all `
+      + `of ${REQUIRED.join(', ')} — a partial store would disable a security rule silently `
+      + 'rather than loudly.');
+  }
+  return store;
+}
+
 // ---------------------------------------------------------------- baseUrl canonicalisation
 
 /** RFC 3986 `pchar` plus '/' — the only characters an accepted path may carry. Everything
@@ -2148,6 +2259,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 +2417,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 +2483,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,
@@ -2342,6 +2496,7 @@ export function createAgentEntry({
   howToUrl = FIRST_KNOCK_URL,
   observer = null,
   wbaVerifiers = null,
+  store = null,
 } = {}) {
   if (!seedHex) throw new TypeError('createAgentEntry: seedHex is required');
   if (!baseUrl) throw new TypeError('createAgentEntry: baseUrl is required (it is signed into the card)');
@@ -2404,7 +2559,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
@@ -2485,6 +2643,53 @@ export function createAgentEntry({
   // Unlike the ledger it is READ on every message, so only a real store can carry it.
   const deviceOwner = new Map();
   const replay = new ReplayGuard();
+
+  // ---------------------------------------------------------------- the state seam (T105)
+  //
+  // WHY. The three structures above live in CLOSURE MEMORY, and a serverless instance keeps
+  // none of them between requests. The round-trip shape suits those platforms perfectly —
+  // one signed POST in, one signed reply out, nothing to keep awake — so what blocks them is
+  // not the shape but the STATE. Losing `replay` re-opens every message inside the freshness
+  // window to replay; losing `deviceOwner` resets the no-re-ownership rule to
+  // trust-on-first-use at every cold start.
+  //
+  // `store` is an OPTIONAL duck-typed object whose five methods may each return a value or a
+  // promise:
+  //
+  //   seenMessage(messageId, ttlSeconds) -> bool   TRUE when the id was NEW (and is now
+  //                                                remembered). The test and the remember
+  //                                                MUST be atomic in the backing store.
+  //   getAccount(did)          -> row | null
+  //   putAccount(did, row)     -> void             row === null DELETES the row.
+  //   getDeviceOwner(deviceDid)-> ownerDid | null
+  //   putDeviceOwner(dev, own) -> void
+  //
+  // Rate counters are deliberately NOT in this interface, and that is the approved design,
+  // not an omission: a bound that costs a store write per request is its own denial of
+  // service, and losing one fails open for a single minute — a bounded loss, unlike a lost
+  // replay set or a lost pin.
+  //
+  // WITH NO STORE the default below is SYNCHRONOUS and wraps exactly the Maps above, so the
+  // no-store path stays byte-identical and `handleRequest` (the sync entry point) keeps
+  // working. With a store the message path returns a promise, which `route()` already
+  // propagates and `handleRequestAsync` already awaits.
+  const memoryStore = {
+    seenMessage: (messageId) => replay.checkAndRemember(messageId),
+    getAccount: (did) => ledger.get(did) ?? null,
+    putAccount: (did, row) => {
+      if (row === null) { ledger.delete(did); return; }
+      ledger.set(did, row);
+      while (ledger.size > maxAccounts) {
+        const oldest = ledger.keys().next();
+        if (oldest.done) break;
+        ledger.delete(oldest.value);
+      }
+    },
+    getDeviceOwner: (deviceDid) => deviceOwner.get(deviceDid) ?? null,
+    putDeviceOwner: (deviceDid, ownerDid) => { deviceOwner.set(deviceDid, ownerDid); },
+  };
+  const state = store ? asStore(store) : memoryStore;
+  const storeIsExternal = Boolean(store);
   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
@@ -2680,25 +2885,24 @@ export function createAgentEntry({
     return sigEnvelope;
   }
 
+  /** Record contact from an account. Returns the row (or a promise of it, with a store). */
   function noteContact(accountDid) {
     const now = nowEpoch();
-    const row = ledger.get(accountDid);
-    if (row) {
-      row.messages += 1;
-      row.last_seen = now;
-      return row;
-    }
-    // FIRST CONTACT IS ACCOUNT CREATION. There is no signup form: the sender proved control
-    // of a device key one line above, which is strictly more than an email link. The row is
-    // keyed by the ACCOUNT (the owner when bound), so sibling devices are one customer.
-    const fresh = { first_seen: now, last_seen: now, messages: 1 };
-    ledger.set(accountDid, fresh);
-    while (ledger.size > maxAccounts) {
-      const oldest = ledger.keys().next();
-      if (oldest.done) break;
-      ledger.delete(oldest.value);
-    }
-    return fresh;
+    return then1(state.getAccount(accountDid), (row) => {
+      if (row) {
+        // A store hands back a COPY, so the row must be written home again. The in-memory
+        // store hands back the live object and the write is a no-op re-set of the same
+        // reference — one code path, correct for both.
+        const updated = { ...row, messages: (row.messages || 0) + 1, last_seen: now };
+        return then1(state.putAccount(accountDid, updated), () => updated);
+      }
+      // FIRST CONTACT IS ACCOUNT CREATION. There is no signup form: the sender proved
+      // control of a device key one line above, which is strictly more than an email link.
+      // The row is keyed by the ACCOUNT (the owner when bound), so sibling devices are one
+      // customer.
+      const fresh = { first_seen: now, last_seen: now, messages: 1 };
+      return then1(state.putAccount(accountDid, fresh), () => fresh);
+    });
   }
 
   /** When a device that ALREADY has an unbound ledger row first proves its owner, move that
@@ -2706,13 +2910,19 @@ export function createAgentEntry({
    *  resolves to the device DID and must not merge, or stripping a binding would become a
    *  way to read the owner's history. */
   function foldDeviceIntoOwner(deviceDid, ownerDid) {
-    const devRow = ledger.get(deviceDid);
-    if (!devRow) return;
-    ledger.delete(deviceDid);
-    const ownerRow = ledger.get(ownerDid);
-    if (!ownerRow) { ledger.set(ownerDid, devRow); return; }
-    ownerRow.messages += devRow.messages || 0;
-    ownerRow.first_seen = Math.min(ownerRow.first_seen, devRow.first_seen);
+    return then1(state.getAccount(deviceDid), (devRow) => {
+      if (!devRow) return undefined;
+      return then1(state.putAccount(deviceDid, null), () =>
+        then1(state.getAccount(ownerDid), (ownerRow) => {
+          if (!ownerRow) return state.putAccount(ownerDid, devRow);
+          const merged = {
+            ...ownerRow,
+            messages: (ownerRow.messages || 0) + (devRow.messages || 0),
+            first_seen: Math.min(ownerRow.first_seen, devRow.first_seen),
+          };
+          return state.putAccount(ownerDid, merged);
+        }));
+    });
   }
 
   /**
@@ -2760,17 +2970,18 @@ export function createAgentEntry({
     if (!verifyDeviceBindingV2(binding, { now, expectedDeviceDid: from })) {
       return { ok: false, reason: 'device binding does not verify' };
     }
-    const pinned = deviceOwner.get(from);
-    if (pinned !== undefined && pinned !== rootDid) {
-      return { ok: false, reason:
-        'device is already bound to a different owner (a device DID is never re-owned '
-        + '— a new owner means a new device key)' };
-    }
-    if (pinned === undefined) {
-      deviceOwner.set(from, rootDid);
-      foldDeviceIntoOwner(from, rootDid);
-    }
-    return { ok: true, account: rootDid };
+    return then1(state.getDeviceOwner(from), (pinned) => {
+      if (pinned !== null && pinned !== undefined && pinned !== rootDid) {
+        return { ok: false, reason:
+          'device is already bound to a different owner (a device DID is never re-owned '
+          + '— a new owner means a new device key)' };
+      }
+      if (pinned === null || pinned === undefined) {
+        return then1(state.putDeviceOwner(from, rootDid), () =>
+          then1(foldDeviceIntoOwner(from, rootDid), () => ({ ok: true, account: rootDid })));
+      }
+      return { ok: true, account: rootDid };
+    });
   }
 
   /** The FROZEN backend-handoff shape (agent/webhookwake.py::_envelope). The site's own
@@ -3051,16 +3262,19 @@ export function createAgentEntry({
           `the anonymous lane is limited to ${anonRatePerMin} replies per minute — `
           + 'sign your message to lift the bound');
       }
-      if (!replay.checkAndRemember(msg.messageId)) {
-        return rpcError(reqId, ERRORS.REPLAY_REJECTED, 'duplicate messageId (replay) detected');
-      }
-      // T107: the interesting case — an anonymous inquiry whose TRANSPORT a known key
-      // signed. `verified` STAYS false (the WBA signature covers @authority +
-      // signature-agent, not the text), no ledger row is minted (the header set is a
-      // bearer credential and replayable while it lives), and the anon rate bound
-      // above already applied. Identify, don't enrol.
-      return respond(backendEnvelope(msg, { verified: false, peerDid: null,
-        wbaDid: wbaIdentify(reqHeaders) }), reqId, msg, '');
+      return then1(state.seenMessage(msg.messageId, REPLAY_TTL_S), (fresh) => {
+        if (!fresh) {
+          return rpcError(reqId, ERRORS.REPLAY_REJECTED,
+            'duplicate messageId (replay) detected');
+        }
+        // T107: the interesting case — an anonymous inquiry whose TRANSPORT a known key
+        // signed. `verified` STAYS false (the WBA signature covers @authority +
+        // signature-agent, not the text), no ledger row is minted (the header set is a
+        // bearer credential and replayable while it lives), and the anon rate bound
+        // above already applied. Identify, don't enrol.
+        return respond(backendEnvelope(msg, { verified: false, peerDid: null,
+          wbaDid: wbaIdentify(reqHeaders) }), reqId, msg, '');
+      });
     }
     // 5. addressed to someone else. Checked BEFORE decoding `from`, so a junk DID in a
     //    misaddressed message never reaches the base58 decoder.
@@ -3085,12 +3299,13 @@ export function createAgentEntry({
     if (!Number.isSafeInteger(ts) || Math.abs(nowEpoch() - ts) > CLOCK_WINDOW_S) {
       return rpcError(reqId, ERRORS.REPLAY_REJECTED, 'timestamp out of range (clock skew or replay)');
     }
-    // 7. the signature itself, under the key DERIVED FROM `from`. (`messageId`'s type was
-    //    settled by the shape gate: a non-string never reaches here on either implementation.)
+    // 7. the signature itself. Payload `from` is the root DID; the verifying key is
+    //    the delegated op-key when a valid inline KeyState is attached (T142 A2).
     const messageId = msg.messageId;
     const fields = { from, to, messageId, contextId: msg.contextId ?? null,
       timestamp: ts, text, sig };
-    if (!verifyEnvelope(fields, { recipientDid: did })) {
+    const signerDid = resolveOpDid(from, meta.keystate, ts);
+    if (!verifyEnvelope(fields, { recipientDid: did, signerDid })) {
       return rpcError(reqId, ERRORS.UNAUTHENTICATED, 'signature does not match');
     }
     // 8. duplicate messageId inside the replay window — AFTER the verify, and the ORDER is the
@@ -3102,40 +3317,54 @@ export function createAgentEntry({
     //    rule the signed lane's ceiling already follows one step below, for the same reason; it
     //    was simply never applied here. The cost of the swap is one Ed25519 verify spent on a
     //    replayed VALID message, which an attacker must first have obtained.
-    if (!replay.checkAndRemember(messageId)) {
-      return rpcError(reqId, ERRORS.REPLAY_REJECTED, 'duplicate messageId (replay) detected');
-    }
-
-    // 9. T102 account layer. An OPTIONAL countersigned v2 binding collapses an owner's device
-    //    DIDs to ONE account; a present-but-INVALID binding fails closed with the SAME
-    //    UNAUTHENTICATED code (never a silent downgrade to unbound). Absent → the device DID.
-    const acct = resolveAccount(meta.binding, from);
-    if (!acct.ok) return rpcError(reqId, ERRORS.UNAUTHENTICATED, acct.reason);
-    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.
-    return respond(backendEnvelope(msg, { verified: true, peerDid: from, ownerDid,
-      wbaDid: wbaIdentify(reqHeaders) }), reqId, msg, from);
+    return then1(state.seenMessage(messageId, REPLAY_TTL_S), (fresh) => {
+      if (!fresh) {
+        return rpcError(reqId, ERRORS.REPLAY_REJECTED, 'duplicate messageId (replay) detected');
+      }
+
+      // 9. T102 account layer. An OPTIONAL countersigned v2 binding collapses an owner's
+      //    device DIDs to ONE account; a present-but-INVALID binding fails closed with the
+      //    SAME UNAUTHENTICATED code (never a silent downgrade to unbound). Absent → the
+      //    device DID.
+      return then1(resolveAccount(meta.binding, from), (acct) => {
+        if (!acct.ok) return rpcError(reqId, ERRORS.UNAUTHENTICATED, acct.reason);
+        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.
+        //
+        //     These two bounds stay IN PROCESS even with an external store, and that is the
+        //     approved design rather than an omission: a ceiling that costs a store write
+        //     per request is its own denial of service, and losing a counter fails open for
+        //     one minute — bounded, unlike a lost replay set or a lost device pin. A
+        //     serverless deployment therefore gets its ceiling per instance; put a real one
+        //     at the edge if that matters.
+        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');
+        }
+
+        return then1(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.
+          respond(backendEnvelope(msg, { verified: true, peerDid: from, ownerDid,
+            wbaDid: wbaIdentify(reqHeaders) }), reqId, msg, from));
+      });
+    });
   }
 
   /** Hand the envelope to the watcher, and make sure it can cost nothing.
@@ -3373,8 +3602,14 @@ export function createAgentEntry({
   function handleRequest(method, path, headers, bodyBuffer) {
     const out = route(method, path, bodyBuffer, headers);
     if (isThenable(out)) {
-      return rpcError(null, ERRORS.INTERNAL_ERROR,
-        'responder is async — serve this agent entry through listen()/handleRequestAsync()');
+      // Two different causes, and an operator can only fix the one they are told about.
+      // A `store` makes EVERY message path async by construction, so saying "responder is
+      // async" to somebody who passed a synchronous responder and a KV store would send
+      // them looking in the wrong place entirely.
+      return rpcError(null, ERRORS.INTERNAL_ERROR, storeIsExternal
+        ? 'this entry has an external store, so every message is answered asynchronously — '
+          + 'serve it through listen()/handleRequestAsync()'
+        : 'responder is async — serve this agent entry through listen()/handleRequestAsync()');
     }
     return out;
   }