@youam/sdk 0.2.0 → 0.4.0

package/dist/cli/index.cjs

@@ -60,11 +60,11 @@ function extractPublicKey(tags) {
   }
   return null;
 }
-async function queryUamTxt(domain, timeout) {
+async function queryUamTxt(domain2, timeout) {
   const controller = new AbortController();
   const timer = timeout != null ? setTimeout(() => controller.abort(), timeout) : void 0;
   try {
-    const records = await (0, import_promises.resolveTxt)(`_uam.${domain}`);
+    const records = await (0, import_promises.resolveTxt)(`_uam.${domain2}`);
     const results = [];
     for (const parts of records) {
       const txtValue = parts.join("");
@@ -79,8 +79,8 @@ async function queryUamTxt(domain, timeout) {
     if (timer != null) clearTimeout(timer);
   }
 }
-async function resolveKeyViaHttps(agentName, domain, timeout) {
-  const url = `https://${domain}/.well-known/uam.json`;
+async function resolveKeyViaHttps(agentName, domain2, timeout) {
+  const url = `https://${domain2}/.well-known/uam.json`;
   try {
     const resp = await fetch(url, {
       signal: AbortSignal.timeout(timeout ?? 1e4)
@@ -114,14 +114,18 @@ var init_dns_verifier = __esm({
 // src/cli/index.ts
 var import_commander = require("commander");
 
+// src/version.ts
+var SDK_VERSION = "0.4.0";
+
 // src/cli/commands/init.ts
 var import_node_os5 = require("os");
-var import_node_fs5 = require("fs");
-var import_node_path5 = require("path");
+var import_node_fs6 = require("fs");
+var import_node_path7 = require("path");
 
 // src/protocol/types.ts
 var UAM_VERSION = "0.1";
 var MAX_ENVELOPE_SIZE = 65536;
+var MAX_ENVELOPE_AGE = 300;
 function b64Encode(data) {
   return Buffer.from(data).toString("base64url");
 }
@@ -195,6 +199,18 @@ var KeyPinningError = class _KeyPinningError extends UAMError {
     Object.setPrototypeOf(this, _KeyPinningError.prototype);
   }
 };
+var SendRefusedError = class extends UAMError {
+  messageId;
+  code;
+  detail;
+  constructor(messageId, code, detail) {
+    super(`Relay refused message ${messageId}: [${code}] ${detail ?? ""}`.trimEnd());
+    this.name = "SendRefusedError";
+    this.messageId = messageId;
+    this.code = code;
+    this.detail = detail;
+  }
+};
 
 // src/protocol/address.ts
 var ADDRESS_RE = /^(?<agent>[a-z0-9][a-z0-9_-]{0,62}[a-z0-9]|[a-z0-9])::(?<domain>[a-z0-9](?:[a-z0-9.-]{0,253}[a-z0-9])?)$/;
@@ -321,11 +337,11 @@ function encryptPayload(plaintext, senderSigningKey, recipientVerifyKey) {
   try {
     const senderCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_sk_to_curve25519(senderSigningKey);
     const recipientCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_pk_to_curve25519(recipientVerifyKey);
-    const nonce = import_libsodium_wrappers.default.randombytes_buf(import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
-    const encrypted = import_libsodium_wrappers.default.crypto_box_easy(plaintext, nonce, recipientCurve, senderCurve);
-    const combined = new Uint8Array(nonce.length + encrypted.length);
-    combined.set(nonce, 0);
-    combined.set(encrypted, nonce.length);
+    const nonce2 = import_libsodium_wrappers.default.randombytes_buf(import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
+    const encrypted = import_libsodium_wrappers.default.crypto_box_easy(plaintext, nonce2, recipientCurve, senderCurve);
+    const combined = new Uint8Array(nonce2.length + encrypted.length);
+    combined.set(nonce2, 0);
+    combined.set(encrypted, nonce2.length);
     return b64Encode(combined);
   } catch (err) {
     if (err instanceof EncryptionError) throw err;
@@ -335,11 +351,11 @@ function encryptPayload(plaintext, senderSigningKey, recipientVerifyKey) {
 function decryptPayload(ciphertextB64, recipientSigningKey, senderVerifyKey) {
   try {
     const combined = b64Decode(ciphertextB64);
-    const nonce = combined.slice(0, import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
+    const nonce2 = combined.slice(0, import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
     const ciphertext = combined.slice(import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
     const recipientCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_sk_to_curve25519(recipientSigningKey);
     const senderCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_pk_to_curve25519(senderVerifyKey);
-    return import_libsodium_wrappers.default.crypto_box_open_easy(ciphertext, nonce, senderCurve, recipientCurve);
+    return import_libsodium_wrappers.default.crypto_box_open_easy(ciphertext, nonce2, senderCurve, recipientCurve);
   } catch (err) {
     if (err instanceof DecryptionError) throw err;
     throw new DecryptionError(err instanceof Error ? err.message : String(err));
@@ -447,7 +463,7 @@ async function createEnvelope(fromAddress, toAddress, messageType, payloadPlaint
   parseAddress(fromAddress);
   parseAddress(toAddress);
   const messageId = (0, import_node_crypto2.randomUUID)();
-  const nonce = generateNonce();
+  const nonce2 = generateNonce();
   const timestamp = utcTimestamp();
   let encryptedPayload;
   if (typeValue === "handshake.request" /* HANDSHAKE_REQUEST */) {
@@ -466,7 +482,7 @@ async function createEnvelope(fromAddress, toAddress, messageType, payloadPlaint
     toAddress,
     timestamp,
     type: typeValue,
-    nonce,
+    nonce: nonce2,
     payload: encryptedPayload,
     signature: "",
     threadId: options?.threadId,
@@ -485,7 +501,7 @@ async function createEnvelope(fromAddress, toAddress, messageType, payloadPlaint
     toAddress,
     timestamp,
     type: typeValue,
-    nonce,
+    nonce: nonce2,
     payload: encryptedPayload,
     signature,
     threadId: options?.threadId,
@@ -577,8 +593,8 @@ function contactCardFromDict(d, options) {
   }
   return card;
 }
-async function createContactCard(address, displayName, relay, signingKey, options) {
-  parseAddress(address);
+async function createContactCard(address2, displayName, relay, signingKey, options) {
+  parseAddress(address2);
   const verifyKey = signingKey.slice(32);
   const pubKeyB64 = serializeVerifyKey(verifyKey);
   const fp = publicKeyFingerprint(verifyKey);
@@ -588,7 +604,7 @@ async function createContactCard(address, displayName, relay, signingKey, option
   ];
   const tempCard = {
     version: UAM_VERSION,
-    address,
+    address: address2,
     displayName,
     description: options?.description,
     system: options?.system,
@@ -605,7 +621,7 @@ async function createContactCard(address, displayName, relay, signingKey, option
   const signature = signMessage(canonicalize(signable), signingKey);
   return Object.freeze({
     version: UAM_VERSION,
-    address,
+    address: address2,
     displayName,
     description: options?.description,
     system: options?.system,
@@ -632,10 +648,163 @@ function verifyContactCard(card) {
   verifySignature(canonicalize(signable), card.signature, vk);
 }
 
+// src/protocol/signed.ts
+var import_node_crypto3 = require("crypto");
+
+// src/protocol/didkey.ts
+var B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var PREFIX = {
+  ed25519: new Uint8Array([237, 1]),
+  p256: new Uint8Array([128, 36])
+};
+var LENGTH = { ed25519: 32, p256: 33 };
+var InvalidDidKeyError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidDidKeyError";
+  }
+};
+function b58decode(text) {
+  let n = 0n;
+  for (const c of text) {
+    const i = B58.indexOf(c);
+    if (i < 0) throw new InvalidDidKeyError(`not base58btc: ${JSON.stringify(c)}`);
+    n = n * 58n + BigInt(i);
+  }
+  const body = [];
+  while (n > 0n) {
+    body.unshift(Number(n & 0xffn));
+    n >>= 8n;
+  }
+  let zeros = 0;
+  while (zeros < text.length && text[zeros] === "1") zeros += 1;
+  return new Uint8Array([...new Array(zeros).fill(0), ...body]);
+}
+function checkKey(kind, key) {
+  if (key.length !== LENGTH[kind]) {
+    throw new InvalidDidKeyError(`${kind} key must be ${LENGTH[kind]} bytes`);
+  }
+  if (kind === "p256" && key[0] !== 2 && key[0] !== 3) {
+    throw new InvalidDidKeyError("P-256 key must be a compressed point");
+  }
+}
+function decodeDidKey(did2) {
+  if (typeof did2 !== "string" || !did2.startsWith("did:key:z")) {
+    throw new InvalidDidKeyError("not a did:key with base58btc multibase");
+  }
+  const raw = b58decode(did2.slice("did:key:z".length));
+  for (const kind of Object.keys(PREFIX)) {
+    const prefix = PREFIX[kind];
+    if (raw.length >= prefix.length && prefix.every((b, i) => raw[i] === b)) {
+      const key = raw.slice(prefix.length);
+      checkKey(kind, key);
+      return { kind, key };
+    }
+  }
+  throw new InvalidDidKeyError("unsupported key type");
+}
+
+// src/protocol/signed.ts
+var MAX_INT = 2 ** 53 - 1;
+var SignedObjectError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "SignedObjectError";
+  }
+};
+var has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+var HASH_RE = /^[A-Za-z0-9_-]{43}$/;
+var OWNER_ID_RE = /^[A-Za-z0-9_-]{22}$/;
+var NONCE_RE = /^[A-Za-z0-9_-]{16,64}$/;
+var SECRET_RE = /^[A-Za-z0-9_-]{22}$/;
+var DOMAIN_RE = /^(?=.{1,253}$)[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)+$/;
+function fail(path, why) {
+  throw new SignedObjectError(`${path}: ${why}`);
+}
+var matching = (re, what) => (v, p) => {
+  if (typeof v !== "string" || !re.test(v)) fail(p, `must be ${what}`);
+};
+var hash = matching(HASH_RE, "a hash (43 base64url characters)");
+var ownerId = matching(OWNER_ID_RE, "an owner id (22 base64url characters)");
+var nonce = matching(NONCE_RE, "a nonce (16-64 base64url characters)");
+var secret = matching(SECRET_RE, "a secret (22 base64url characters)");
+var domain = matching(DOMAIN_RE, "a lowercase domain");
+var constant = (expected) => (v, p) => {
+  if (v !== expected) fail(p, `must be ${JSON.stringify(expected)}`);
+};
+var oneOf = (...options) => (v, p) => {
+  if (typeof v !== "string" || !options.includes(v)) fail(p, `must be one of ${options.join(", ")}`);
+};
+var address = (v, p) => {
+  if (typeof v !== "string") fail(p, "must be an address");
+  let full;
+  try {
+    full = parseAddress(v).full;
+  } catch {
+    return fail(p, "must be an address");
+  }
+  if (full !== v) fail(p, "must be an address in canonical (lowercase) form");
+};
+var did = (kind) => (v, p) => {
+  let found;
+  try {
+    found = decodeDidKey(v).kind;
+  } catch (err) {
+    return fail(p, err instanceof Error ? err.message : String(err));
+  }
+  if (found !== kind) fail(p, `must be a ${kind} did:key`);
+};
+var list = (item, minLen = 1, maxLen = 64) => (v, p) => {
+  if (!Array.isArray(v) || v.length < minLen || v.length > maxLen) {
+    fail(p, `must be a list of ${minLen}-${maxLen} items`);
+  }
+  v.forEach((entry, i) => item(entry, `${p}[${i}]`));
+};
+var object = (required, optional = {}) => (v, p) => {
+  if (!isPlainObject(v)) fail(p, "must be an object");
+  for (const key of Object.keys(v)) {
+    if (!has(required, key) && !has(optional, key)) fail(`${p}.${key}`, "unknown member");
+  }
+  for (const [key, member] of Object.entries(required)) {
+    if (!has(v, key)) fail(`${p}.${key}`, "missing");
+    member(v[key], `${p}.${key}`);
+  }
+  for (const [key, member] of Object.entries(optional)) {
+    if (has(v, key)) member(v[key], `${p}.${key}`);
+  }
+};
+var location = (v, p) => {
+  if (v !== "shared") address(v, p);
+};
+var access = object({ actions: list(oneOf("message"), 1, 1), locations: list(location) });
+var ownerRef = object({ relay: domain, ownerId, keysHash: hash });
+var ownerRefNoKeys = object({ relay: domain, ownerId });
+var passkey = did("p256");
+var agentKey = did("ed25519");
+var keysOwner = object({ relay: domain }, { ownerId });
+var DAY = 24 * 60 * 60 * 1e3;
+var SUBJECTS = {
+  owner: object({ kind: constant("owner"), owner: ownerRef }),
+  invitee: object({ kind: constant("invitee"), invite: hash }),
+  agent: object({ kind: constant("agent"), id: agentKey, address })
+};
+
+// src/protocol/webauthn.ts
+var import_node_crypto4 = require("crypto");
+var import_p256 = require("@noble/curves/p256");
+
 // src/sdk/config.ts
 var import_node_os = require("os");
 var import_node_path = require("path");
 var DEFAULT_RELAY_URL = "https://relay.youam.network";
+function trimRelayUrl(url) {
+  return url.replace(/\/+$/, "");
+}
 var VALID_POLICIES = /* @__PURE__ */ new Set([
   "auto-accept",
   "approval-required",
@@ -652,9 +821,13 @@ var SDKConfig = class {
   transportType;
   trustPolicy;
   relayDomain;
+  /** The domain the caller chose, if any; null when only derived. */
+  explicitRelayDomain;
   constructor(options) {
     this.name = options.name;
-    this.relayUrl = options.relayUrl ?? process.env["UAM_RELAY_URL"] ?? DEFAULT_RELAY_URL;
+    this.relayUrl = trimRelayUrl(
+      options.relayUrl ?? process.env["UAM_RELAY_URL"] ?? DEFAULT_RELAY_URL
+    );
     if (options.relayWsUrl) {
       this.relayWsUrl = options.relayWsUrl;
     } else {
@@ -665,6 +838,7 @@ var SDKConfig = class {
       this.relayWsUrl = wsUrl;
     }
     const envDomain = process.env["UAM_RELAY_DOMAIN"];
+    this.explicitRelayDomain = envDomain || options.relayDomain || null;
     if (envDomain) {
       this.relayDomain = envDomain;
     } else if (options.relayDomain) {
@@ -768,17 +942,54 @@ var KeyManager = class {
     (0, import_node_fs.writeFileSync)(tokenPath, token);
     this._setPermissions(tokenPath);
   }
+  /**
+   * Store the address `relayUrl` gave this agent.
+   */
+  saveAddress(name, address2, relayUrl) {
+    (0, import_node_fs.mkdirSync)(this._keyDir, { recursive: true });
+    (0, import_node_fs.writeFileSync)(
+      (0, import_node_path2.join)(this._keyDir, `${name}.address`),
+      JSON.stringify({ address: address2, relay_url: relayUrl })
+    );
+  }
+  /**
+   * Load the address saved for `relayUrl`.
+   *
+   * Returns null if there is none: the file is missing, unreadable or
+   * malformed, or it belongs to another relay.
+   */
+  loadAddress(name, relayUrl) {
+    try {
+      const path = (0, import_node_path2.join)(this._keyDir, `${name}.address`);
+      const saved = JSON.parse((0, import_node_fs.readFileSync)(path, "utf-8"));
+      const address2 = saved?.address;
+      const savedRelay = saved?.relay_url;
+      if (typeof address2 !== "string" || typeof savedRelay !== "string") {
+        return null;
+      }
+      if (trimRelayUrl(savedRelay) !== trimRelayUrl(relayUrl)) return null;
+      parseAddress(address2);
+      return address2;
+    } catch {
+      return null;
+    }
+  }
   /**
    * Load a previously saved token, or return null.
    *
    * Checks UAM_TOKEN env var first, then file-based storage,
-   * then legacy .api_key files for backward compatibility.
+   * then legacy .api_key files for backward compatibility. With `relayUrl`,
+   * a saved token that belongs to another relay counts as none, so it is
+   * only offered to the relay that issued it.
    */
-  loadToken(name) {
+  loadToken(name, relayUrl) {
     const envToken = process.env["UAM_TOKEN"];
     if (envToken) {
       return envToken.trim();
     }
+    if (relayUrl !== void 0 && this._savedForAnotherRelay(name, relayUrl)) {
+      return null;
+    }
     const tokenPath = (0, import_node_path2.join)(this._keyDir, `${name}.token`);
     if ((0, import_node_fs2.existsSync)(tokenPath)) {
       return (0, import_node_fs.readFileSync)(tokenPath, "utf-8").trim();
@@ -789,6 +1000,20 @@ var KeyManager = class {
     }
     return null;
   }
+  /**
+   * True if the saved address says this agent's files are another relay's.
+   * A missing or damaged file says nothing.
+   */
+  _savedForAnotherRelay(name, relayUrl) {
+    try {
+      const path = (0, import_node_path2.join)(this._keyDir, `${name}.address`);
+      const saved = JSON.parse((0, import_node_fs.readFileSync)(path, "utf-8"));
+      const savedRelay = saved?.relay_url;
+      return typeof savedRelay === "string" && trimRelayUrl(savedRelay) !== trimRelayUrl(relayUrl);
+    } catch {
+      return false;
+    }
+  }
   /** Set file permissions to 0o600 (owner read/write only). */
   _setPermissions(path) {
     if ((0, import_node_os3.platform)() !== "win32") {
@@ -812,10 +1037,73 @@ var KeyManager = class {
   }
 };
 
+// src/sdk/agent.ts
+var import_node_path5 = require("path");
+
+// src/sdk/freshness.ts
+var RELAY_META_FEATURE = "relay_meta";
+var STORED_MAIL_MAX_AGE = 7 * 86400;
+var ISO_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+function relayVouches(raw, signedAt, now, relayDomain) {
+  const meta = raw["relay_meta"];
+  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
+    return false;
+  }
+  const stamp = meta;
+  if (stamp["v"] !== 1 || stamp["relay"] !== relayDomain) return false;
+  if (stamp["stored"] !== true) return false;
+  const received = stamp["received_at"];
+  if (typeof received !== "string" || !ISO_TIME.test(received)) return false;
+  const receivedAt = Date.parse(received);
+  if (Number.isNaN(receivedAt)) return false;
+  const window = MAX_ENVELOPE_AGE * 1e3;
+  const age = now - signedAt;
+  return Math.abs(receivedAt - signedAt) <= window && age >= 0 && age <= STORED_MAIL_MAX_AGE * 1e3 + window;
+}
+
+// src/sdk/message.ts
+var SEND_STATUSES = [
+  "delivered",
+  "stored",
+  "relayed",
+  "queued",
+  "duplicate",
+  "dropped",
+  "pending",
+  "accepted",
+  "unknown"
+];
+function sendStatus(answer) {
+  if (answer === null) return "unknown";
+  const status = answer["status"];
+  if (typeof status === "string" && SEND_STATUSES.includes(status) && status !== "accepted" && status !== "unknown") {
+    return status;
+  }
+  return "accepted";
+}
+var PENDING_NOTE = "Not delivered: {to} only accepts messages from approved contacts. Do not resend it.";
+function pendingNote(to) {
+  return PENDING_NOTE.replace("{to}", to);
+}
+
 // src/sdk/contact-book.ts
 var import_node_fs3 = require("fs");
 var import_node_path3 = require("path");
 var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+
+// src/sdk/log.ts
+var log = {
+  warn(message) {
+    console.warn(`[uam] ${message}`);
+  },
+  info(message) {
+    if (process.env["UAM_DEBUG"]) {
+      console.info(`[uam] ${message}`);
+    }
+  }
+};
+
+// src/sdk/contact-book.ts
 var ContactBook = class {
   _dbPath;
   _db = null;
@@ -895,36 +1183,36 @@ var ContactBook = class {
   /**
    * Check if an address is in the contact book (in-memory, no I/O).
    */
-  isKnown(address) {
-    return this._knownAddresses.has(address);
+  isKnown(address2) {
+    return this._knownAddresses.has(address2);
   }
   /**
    * Check if an address matches any blocked pattern (O(1) set lookup).
    */
-  isBlocked(address) {
-    if (this._blockedExact.has(address)) {
+  isBlocked(address2) {
+    if (this._blockedExact.has(address2)) {
       return true;
     }
-    if (address.includes("::")) {
-      const domain = address.split("::")[1];
-      return this._blockedDomains.has(domain);
+    if (address2.includes("::")) {
+      const domain2 = address2.split("::")[1];
+      return this._blockedDomains.has(domain2);
     }
     return false;
   }
   /**
    * Look up the public key for a known contact.
    */
-  getPublicKey(address) {
+  getPublicKey(address2) {
     if (this._db === null) return null;
-    const row = this._db.prepare("SELECT public_key FROM contacts WHERE address = ?").get(address);
+    const row = this._db.prepare("SELECT public_key FROM contacts WHERE address = ?").get(address2);
     return row?.public_key ?? null;
   }
   /**
    * Return the relay URLs for a known contact (CARD-04).
    */
-  getRelayUrls(address) {
+  getRelayUrls(address2) {
     if (this._db === null) return null;
-    const row = this._db.prepare("SELECT relay, relays_json FROM contacts WHERE address = ?").get(address);
+    const row = this._db.prepare("SELECT relay, relays_json FROM contacts WHERE address = ?").get(address2);
     if (!row) return null;
     if (row.relays_json !== null) {
       return JSON.parse(row.relays_json);
@@ -936,11 +1224,30 @@ var ContactBook = class {
   }
   /**
    * Add or update a contact (upsert).
+   *
+   * Refuses to replace the key of a contact whose trust_state is "pinned"
+   * or "verified" with a different key, unless `force: true` is passed (for
+   * a deliberate key rotation, which is logged). Matches the Python SDK's
+   * ContactBook.add_contact.
+   *
+   * @throws {KeyPinningError} If a pinned/verified contact's key would be
+   *   replaced by a different key without `force`.
    */
-  addContact(address, publicKey, options) {
+  addContact(address2, publicKey, options) {
     if (this._db === null) {
       throw new Error("ContactBook not open. Call open() first.");
     }
+    const existing = this._db.prepare("SELECT public_key, trust_state FROM contacts WHERE address = ?").get(address2);
+    if (existing !== void 0 && (existing.trust_state === "pinned" || existing.trust_state === "verified") && existing.public_key !== publicKey) {
+      if (!options?.force) {
+        throw new KeyPinningError(
+          `Refusing to overwrite ${existing.trust_state} contact ${JSON.stringify(address2)}: stored public key does not match the new key. Pass force: true to rotate.`
+        );
+      }
+      log.warn(
+        `Force-replacing the key of ${existing.trust_state} contact ${address2} (key rotation)`
+      );
+    }
     const displayName = options?.displayName ?? null;
     const trustState = options?.trustState ?? "trusted";
     const trustSource = options?.trustSource ?? null;
@@ -957,8 +1264,8 @@ var ContactBook = class {
            relay = COALESCE(excluded.relay, contacts.relay),
            relays_json = COALESCE(excluded.relays_json, contacts.relays_json),
            last_seen = datetime('now')`
-    ).run(address, publicKey, displayName, trustState, trustSource, relay, relaysJson);
-    this._knownAddresses.add(address);
+    ).run(address2, publicKey, displayName, trustState, trustSource, relay, relaysJson);
+    this._knownAddresses.add(address2);
   }
   /**
    * Return all contacts sorted by last_seen DESC.
@@ -979,13 +1286,13 @@ var ContactBook = class {
   /**
    * Store a pending handshake request.
    */
-  addPending(address, contactCardJson) {
+  addPending(address2, contactCardJson) {
     if (this._db === null) {
       throw new Error("ContactBook not open. Call open() first.");
     }
     this._db.prepare(
       `INSERT OR REPLACE INTO pending_handshakes (address, contact_card) VALUES (?, ?)`
-    ).run(address, contactCardJson);
+    ).run(address2, contactCardJson);
   }
   /**
    * Retrieve all pending handshake requests.
@@ -1004,9 +1311,9 @@ var ContactBook = class {
   /**
    * Remove a pending handshake request.
    */
-  removePending(address) {
+  removePending(address2) {
     if (this._db === null) return;
-    this._db.prepare("DELETE FROM pending_handshakes WHERE address = ?").run(address);
+    this._db.prepare("DELETE FROM pending_handshakes WHERE address = ?").run(address2);
   }
   /**
    * Return pending handshakes older than N days.
@@ -1026,31 +1333,31 @@ var ContactBook = class {
   /**
    * Return the trust_state for an address, or null if unknown.
    */
-  getTrustState(address) {
+  getTrustState(address2) {
     if (this._db === null) return null;
-    const row = this._db.prepare("SELECT trust_state FROM contacts WHERE address = ?").get(address);
+    const row = this._db.prepare("SELECT trust_state FROM contacts WHERE address = ?").get(address2);
     return row?.trust_state ?? null;
   }
   /**
    * Set the pinned_at timestamp and trust_state='pinned' for a contact (TOFU).
    */
-  setPinnedAt(address) {
+  setPinnedAt(address2) {
     if (this._db === null) {
       throw new Error("ContactBook not open. Call open() first.");
     }
     this._db.prepare(
       "UPDATE contacts SET pinned_at = datetime('now'), trust_state = 'pinned' WHERE address = ?"
-    ).run(address);
+    ).run(address2);
   }
   /**
    * Remove a contact by address. Returns true if a contact was deleted.
    */
-  removeContact(address) {
+  removeContact(address2) {
     if (this._db === null) {
       throw new Error("ContactBook not open. Call open() first.");
     }
-    const result = this._db.prepare("DELETE FROM contacts WHERE address = ?").run(address);
-    this._knownAddresses.delete(address);
+    const result = this._db.prepare("DELETE FROM contacts WHERE address = ?").run(address2);
+    this._knownAddresses.delete(address2);
     return result.changes > 0;
   }
   /**
@@ -1058,8 +1365,8 @@ var ContactBook = class {
    *
    * Convenience helper for inbound message filtering (CARD-05, TOFU-02).
    */
-  isTrustedOrVerified(address) {
-    const state = this.getTrustState(address);
+  isTrustedOrVerified(address2) {
+    const state = this.getTrustState(address2);
     return state === "trusted" || state === "verified" || state === "pinned";
   }
   /**
@@ -1113,6 +1420,18 @@ var ContactBook = class {
 };
 
 // src/sdk/handshake.ts
+function bindCardToEnvelope(card, envelope, senderVk) {
+  if (card.address !== envelope.fromAddress) {
+    throw new InvalidEnvelopeError(
+      `Contact card address ${JSON.stringify(card.address)} does not match envelope sender ${JSON.stringify(envelope.fromAddress)}`
+    );
+  }
+  if (card.publicKey !== serializeVerifyKey(senderVk)) {
+    throw new InvalidEnvelopeError(
+      "Contact card public_key does not match envelope sender's verify key"
+    );
+  }
+}
 var HandshakeManager = class {
   _contactBook;
   _trustPolicy;
@@ -1155,7 +1474,7 @@ var HandshakeManager = class {
     if (envelope.type === "handshake.request" /* HANDSHAKE_REQUEST */) {
       await this._handleRequest(agent, envelope, senderVk);
     } else if (envelope.type === "handshake.accept" /* HANDSHAKE_ACCEPT */) {
-      await this._handleAccept(envelope, senderVk);
+      await this._handleAccept(agent, envelope, senderVk);
     } else if (envelope.type === "handshake.deny" /* HANDSHAKE_DENY */) {
     }
     return null;
@@ -1173,6 +1492,7 @@ var HandshakeManager = class {
     );
     const card = contactCardFromDict(cardDict);
     verifyContactCard(card);
+    bindCardToEnvelope(card, envelope, senderVk);
     if (this._trustPolicy === "auto-accept") {
       this._contactBook.addContact(card.address, card.publicKey, {
         displayName: card.displayName,
@@ -1191,8 +1511,46 @@ var HandshakeManager = class {
   }
   /**
    * Process a handshake.accept: store the sender as pinned (TOFU).
+   *
+   * Only honoured when:
+   *   1. we previously sent this address a handshake.request
+   *      (trust_state === "handshake-sent"); anything else is an unsolicited
+   *      accept and is dropped. This also means an accept can never
+   *      downgrade a trusted/verified contact to pinned;
+   *   2. the payload decrypts with our key and the sender's key, and parses
+   *      as JSON. Otherwise it is dropped without pinning;
+   *   3. an embedded contact_card, if present, is well-formed, correctly
+   *      self-signed, and bound to the envelope sender (throws otherwise).
    */
-  async _handleAccept(envelope, senderVk) {
+  async _handleAccept(agent, envelope, senderVk) {
+    const prior = this._contactBook.getTrustState(envelope.fromAddress);
+    if (prior !== "handshake-sent") {
+      log.warn(
+        `Ignoring unsolicited handshake.accept from ${envelope.fromAddress} (trust_state=${JSON.stringify(prior)})`
+      );
+      return;
+    }
+    let payload;
+    try {
+      const plaintext = decryptPayload(
+        envelope.payload,
+        agent._keyManager.signingKey,
+        senderVk
+      );
+      payload = JSON.parse(new TextDecoder().decode(plaintext));
+    } catch {
+      log.warn(
+        `Dropping handshake.accept ${envelope.messageId} from ${envelope.fromAddress}: payload could not be decrypted or parsed`
+      );
+      return;
+    }
+    if (payload !== null && typeof payload === "object" && "contact_card" in payload) {
+      const card = contactCardFromDict(
+        payload["contact_card"]
+      );
+      verifyContactCard(card);
+      bindCardToEnvelope(card, envelope, senderVk);
+    }
     const senderPkStr = serializeVerifyKey(senderVk);
     this._contactBook.addContact(envelope.fromAddress, senderPkStr, {
       trustState: "pinned"
@@ -1249,6 +1607,10 @@ var HandshakeManager = class {
   }
 };
 
+// src/sdk/resolver-base.ts
+var AddressResolver = class {
+};
+
 // src/sdk/tier3.ts
 var import_viem = require("viem");
 var DEFAULT_RPC_URL = "https://sepolia.base.org";
@@ -1301,8 +1663,8 @@ var Tier3Resolver = class extends AddressResolver {
       transport: (0, import_viem.http)(rpcUrl)
     });
   }
-  async resolvePublicKey(address, _token, _relayUrl) {
-    const parsed = parseAddress(address);
+  async resolvePublicKey(address2, _token, _relayUrl) {
+    const parsed = parseAddress(address2);
     const name = parsed.domain;
     const cached = this._cache.get(name);
     if (cached && cached.expiresAt > Date.now()) {
@@ -1365,15 +1727,13 @@ var Tier3Resolver = class extends AddressResolver {
 
 // src/sdk/resolver.ts
 init_dns_verifier();
-var AddressResolver = class {
-};
 var Tier1Resolver = class extends AddressResolver {
-  async resolvePublicKey(address, _token, relayUrl) {
+  async resolvePublicKey(address2, _token, relayUrl) {
     const resp = await fetch(
-      `${relayUrl}/api/v1/agents/${address}/public-key`
+      `${relayUrl}/api/v1/agents/${address2}/public-key`
     );
     if (resp.status === 404) {
-      throw new UAMError(`Agent not found: ${address}`);
+      throw new UAMError(`Agent not found: ${address2}`);
     }
     if (!resp.ok) {
       throw new UAMError(
@@ -1385,8 +1745,8 @@ var Tier1Resolver = class extends AddressResolver {
   }
 };
 var Tier2Resolver = class extends AddressResolver {
-  async resolvePublicKey(address, _token, _relayUrl) {
-    const parsed = parseAddress(address);
+  async resolvePublicKey(address2, _token, _relayUrl) {
+    const parsed = parseAddress(address2);
     const txtRecords = await queryUamTxt(parsed.domain);
     for (const txt of txtRecords) {
       const tags = parseUamTxt(txt);
@@ -1398,37 +1758,37 @@ var Tier2Resolver = class extends AddressResolver {
     const httpsKey = await resolveKeyViaHttps(parsed.agent, parsed.domain);
     if (httpsKey) return httpsKey;
     throw new UAMError(
-      `Could not resolve public key for ${address} via DNS or HTTPS`
+      `Could not resolve public key for ${address2} via DNS or HTTPS`
     );
   }
 };
 var SmartResolver = class extends AddressResolver {
-  _relayDomain;
+  relayDomain;
   _tier1;
   _tier2;
   _tier3;
   constructor(relayDomain, tier3Config) {
     super();
-    this._relayDomain = relayDomain;
+    this.relayDomain = relayDomain;
     this._tier1 = new Tier1Resolver();
     this._tier2 = new Tier2Resolver();
     this._tier3 = tier3Config ? new Tier3Resolver(tier3Config) : null;
   }
-  async resolvePublicKey(address, token, relayUrl) {
-    const parsed = parseAddress(address);
-    const domain = parsed.domain;
-    if (domain === this._relayDomain) {
-      return this._tier1.resolvePublicKey(address, token, relayUrl);
+  async resolvePublicKey(address2, token, relayUrl) {
+    const parsed = parseAddress(address2);
+    const domain2 = parsed.domain;
+    if (domain2 === this.relayDomain) {
+      return this._tier1.resolvePublicKey(address2, token, relayUrl);
     }
-    if (domain.includes(".")) {
-      return this._tier2.resolvePublicKey(address, token, relayUrl);
+    if (domain2.includes(".")) {
+      return this._tier2.resolvePublicKey(address2, token, relayUrl);
     }
     if (!this._tier3) {
       throw new UAMError(
-        `Tier 3 resolution requires contract config. Cannot resolve dot-free domain: '${domain}'`
+        `Tier 3 resolution requires contract config. Cannot resolve dot-free domain: '${domain2}'`
       );
     }
-    return this._tier3.resolvePublicKey(address, token, relayUrl);
+    return this._tier3.resolvePublicKey(address2, token, relayUrl);
   }
 };
 
@@ -1437,15 +1797,23 @@ var TransportBase = class {
 };
 
 // src/sdk/transport/http.ts
+async function readAnswer(resp) {
+  try {
+    const body = await resp.json();
+    return body !== null && typeof body === "object" && !Array.isArray(body) ? body : {};
+  } catch {
+    return {};
+  }
+}
 var HTTPTransport = class extends TransportBase {
   _relayUrl;
   _token;
   _address;
-  constructor(relayUrl, token, address) {
+  constructor(relayUrl, token, address2) {
     super();
     this._relayUrl = relayUrl.replace(/\/+$/, "");
     this._token = token;
-    this._address = address;
+    this._address = address2;
   }
   async connect() {
   }
@@ -1465,6 +1833,7 @@ var HTTPTransport = class extends TransportBase {
         `HTTP send failed: ${resp.status} ${resp.statusText}`
       );
     }
+    return readAnswer(resp);
   }
   async receive(limit = 50) {
     const url = new URL(
@@ -1496,8 +1865,11 @@ var import_ws = __toESM(require("ws"), 1);
 var BASE_DELAY = 1;
 var MAX_DELAY = 60;
 var JITTER_RANGE = 1;
+var SEND_SETTLE_SECONDS = 5;
+var ACK_TIMEOUT_SECONDS = 5;
 var WebSocketTransport = class extends TransportBase {
   _url;
+  _token;
   _onMessage;
   _ws = null;
   _pending = [];
@@ -1506,9 +1878,20 @@ var WebSocketTransport = class extends TransportBase {
   _connectReject = null;
   _running = false;
   _reconnectTimeout = null;
+  /** Envelopes sent that the relay hasn't answered yet. */
+  _unanswered = 0;
+  _settling = null;
+  _settled = null;
+  /** Sends waiting for the relay's answer, by message_id. */
+  _waiting = /* @__PURE__ */ new Map();
+  /** @internal How long a close waits, in ms. Replaceable in tests. */
+  _settleMs = SEND_SETTLE_SECONDS * 1e3;
+  /** @internal How long send() waits for an answer, in ms. Replaceable in tests. */
+  _ackMs = ACK_TIMEOUT_SECONDS * 1e3;
   constructor(wsUrl, token, onMessage) {
     super();
-    this._url = `${wsUrl}?token=${token}`;
+    this._url = wsUrl;
+    this._token = token;
     this._onMessage = onMessage ?? null;
   }
   async connect() {
@@ -1529,7 +1912,14 @@ var WebSocketTransport = class extends TransportBase {
       };
     });
   }
+  /**
+   * Close the connection, once the relay has answered what was sent.
+   *
+   * The relay stops reading a socket when it can't write an ack to it, so
+   * closing straight after send() loses every frame but the first.
+   */
   async disconnect() {
+    await this._allAnswered();
     this._running = false;
     if (this._reconnectTimeout !== null) {
       clearTimeout(this._reconnectTimeout);
@@ -1541,12 +1931,42 @@ var WebSocketTransport = class extends TransportBase {
       this._ws = null;
     }
     this._connected = false;
+    this._abandonWaiting();
   }
+  /**
+   * Send an envelope and wait for the relay's answer.
+   *
+   * Resolves with the ack that names the message, or null when none came
+   * within _ackMs or the socket went: the message may still have arrived.
+   * Rejects with SendRefusedError when the relay refuses it by message_id
+   * (relays before 1.1 don't name it, so their refusals end as null).
+   */
   async send(envelope) {
     if (!this._ws || this._ws.readyState !== import_ws.default.OPEN) {
       throw new Error("WebSocket not connected");
     }
+    const messageId = envelope["message_id"];
+    let answer = null;
+    let timer;
+    if (typeof messageId === "string" && !this._waiting.has(messageId)) {
+      answer = new Promise((resolve, reject) => {
+        this._waiting.set(messageId, { resolve, reject });
+        timer = setTimeout(() => {
+          log.warn(
+            `No answer from the relay for ${messageId} within ${this._ackMs / 1e3}s`
+          );
+          this._settle(messageId, null);
+        }, this._ackMs);
+      });
+    }
     this._ws.send(JSON.stringify(envelope));
+    this._unanswered += 1;
+    if (answer === null) return null;
+    try {
+      return await answer;
+    } finally {
+      clearTimeout(timer);
+    }
   }
   async receive(limit = 50) {
     const result = this._pending.slice(0, limit);
@@ -1556,11 +1976,47 @@ var WebSocketTransport = class extends TransportBase {
   async listen(callback) {
     this._onMessage = callback;
   }
+  /** Resolves when nothing is unanswered, or after _settleMs regardless. */
+  _allAnswered() {
+    if (this._unanswered === 0) return Promise.resolve();
+    this._settling ??= new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        log.warn(`Closing with ${this._unanswered} sends unanswered`);
+        this._settled?.();
+      }, this._settleMs);
+      this._settled = () => {
+        clearTimeout(timeout);
+        this._settling = null;
+        this._settled = null;
+        resolve();
+      };
+    });
+    return this._settling;
+  }
+  /** Hand the relay's answer (or a refusal) to the send waiting for it. */
+  _settle(messageId, answer, error) {
+    if (typeof messageId !== "string") return;
+    const waiting = this._waiting.get(messageId);
+    if (!waiting) return;
+    this._waiting.delete(messageId);
+    if (error) waiting.reject(error);
+    else waiting.resolve(answer);
+  }
+  /** The socket went: no answers will come for what it carried. */
+  _abandonWaiting() {
+    const waiting = [...this._waiting.values()];
+    this._waiting.clear();
+    for (const w of waiting) w.resolve(null);
+  }
+  _answered() {
+    this._unanswered = Math.max(0, this._unanswered - 1);
+    if (this._unanswered === 0) this._settled?.();
+  }
   _startConnectionLoop() {
     let attempt = 0;
     const tryConnect = () => {
       if (!this._running) return;
-      const ws = new import_ws.default(this._url);
+      const ws = new import_ws.default(this._url, [`bearer.${this._token}`]);
       this._ws = ws;
       ws.on("open", () => {
         this._connected = true;
@@ -1581,6 +2037,9 @@ var WebSocketTransport = class extends TransportBase {
       ws.on("close", () => {
         this._connected = false;
         this._ws = null;
+        this._unanswered = 0;
+        this._settled?.();
+        this._abandonWaiting();
         if (!this._running) return;
         attempt += 1;
         const delay = Math.min(BASE_DELAY * Math.pow(2, attempt), MAX_DELAY);
@@ -1597,33 +2056,279 @@ var WebSocketTransport = class extends TransportBase {
   }
   _handleMessage(msg) {
     const msgType = msg["type"];
-    if (msgType === "ping") {
-      if (this._ws && this._ws.readyState === import_ws.default.OPEN) {
-        this._ws.send(JSON.stringify({ type: "pong" }));
-      }
-    } else if (msgType === "ack") {
-    } else if (msgType === "error" || "error" in msg) {
-    } else if ("uam_version" in msg) {
+    if ("uam_version" in msg) {
       if (this._onMessage) {
         this._onMessage(msg).catch(() => {
         });
       } else {
         this._pending.push(msg);
       }
+    } else if (msgType === "ping") {
+      if (this._ws && this._ws.readyState === import_ws.default.OPEN) {
+        this._ws.send(JSON.stringify({ type: "pong" }));
+      }
+    } else if (msgType === "ack") {
+      this._answered();
+      this._settle(msg["message_id"], msg);
+    } else if (msgType === "relay.notice") {
+      log.warn(
+        `Relay notice: message ${String(msg["message_id"])} is ${String(msg["status"])}`
+      );
+    } else if (msgType === "error" || "error" in msg) {
+      this._answered();
+      const code = String(msg["error"] ?? msg["code"] ?? "error");
+      const detail = typeof msg["detail"] === "string" ? msg["detail"] : void 0;
+      log.warn(`Relay error: [${code}] ${detail ?? ""}`.trimEnd());
+      const messageId = msg["message_id"];
+      if (typeof messageId === "string") {
+        this._settle(messageId, null, new SendRefusedError(messageId, code, detail));
+      }
     }
   }
 };
 
 // src/sdk/transport/index.ts
-function createTransport(config, token, address, onMessage) {
+function createTransport(config, token, address2, onMessage) {
   if (config.transportType === "http") {
-    return new HTTPTransport(config.relayUrl, token, address);
+    return new HTTPTransport(config.relayUrl, token, address2);
   } else {
     return new WebSocketTransport(config.relayWsUrl, token, onMessage);
   }
 }
 
+// src/sdk/replay-cache.ts
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
+var import_promises2 = require("timers/promises");
+var import_better_sqlite32 = __toESM(require("better-sqlite3"), 1);
+var RETENTION_SECONDS = STORED_MAIL_MAX_AGE + 2 * MAX_ENVELOPE_AGE;
+var PURGE_INTERVAL_MS = 6e4;
+var WAL_ATTEMPTS = 100;
+var WAL_RETRY_MS = 100;
+var SCHEMA = `
+CREATE TABLE IF NOT EXISTS seen_envelopes (
+    from_address TEXT NOT NULL,
+    message_id   TEXT NOT NULL,
+    seen_at      REAL NOT NULL,
+    PRIMARY KEY (from_address, message_id)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS seen_envelopes_seen_at ON seen_envelopes (seen_at);
+CREATE TABLE IF NOT EXISTS replay_meta (
+    key   TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+`;
+function isLocked(err) {
+  const code = err.code;
+  return typeof code === "string" && (code.startsWith("SQLITE_BUSY") || code.startsWith("SQLITE_LOCKED"));
+}
+async function enableWal(db) {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      db.pragma("journal_mode = WAL");
+      return;
+    } catch (err) {
+      if (attempt >= WAL_ATTEMPTS || !isLocked(err)) throw err;
+      await (0, import_promises2.setTimeout)(WAL_RETRY_MS);
+    }
+  }
+}
+var DEFAULT_REPLAY_CACHE_CAPACITY = 1e6;
+var EnvelopeReplayCache = class {
+  capacity;
+  ttlMs;
+  _now;
+  // Map iteration order is insertion order: first key = least recently used.
+  _seen = /* @__PURE__ */ new Map();
+  constructor(options) {
+    const capacity = options?.capacity ?? 1e5;
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new RangeError(
+        `Replay cache capacity must be a positive integer, got ${capacity}`
+      );
+    }
+    this.capacity = capacity;
+    this.ttlMs = options?.ttlMs ?? 3e5;
+    this._now = options?.now ?? (() => Date.now());
+  }
+  get size() {
+    return this._seen.size;
+  }
+  /** True if this pair was seen within the TTL. Records nothing. */
+  has(fromAddress, messageId) {
+    const seenAt = this._seen.get(this._key(fromAddress, messageId));
+    return seenAt !== void 0 && this._now() - seenAt < this.ttlMs;
+  }
+  /**
+   * Return true if this (fromAddress, messageId) pair was already seen
+   * within the TTL (a replay). Otherwise record it and return false.
+   */
+  seenOrRecord(fromAddress, messageId) {
+    const key = this._key(fromAddress, messageId);
+    const now = this._now();
+    const seenAt = this._seen.get(key);
+    if (seenAt !== void 0 && now - seenAt < this.ttlMs) {
+      this._seen.delete(key);
+      this._seen.set(key, seenAt);
+      return true;
+    }
+    this._seen.delete(key);
+    this._seen.set(key, now);
+    while (this._seen.size > this.capacity) {
+      const oldest = this._seen.keys().next().value;
+      this._seen.delete(oldest);
+    }
+    return false;
+  }
+  _key(fromAddress, messageId) {
+    return JSON.stringify([fromAddress, messageId]);
+  }
+};
+var PersistentReplayCache = class {
+  capacity;
+  _path;
+  _now;
+  _db = null;
+  _opening = null;
+  _count = 0;
+  _lastPurge = 0;
+  _createdAt = 0;
+  // Used only while the file is full, for envelopes inside MAX_ENVELOPE_AGE.
+  // One can be signed that far ahead of us and stay acceptable until that far
+  // behind, so its id must last both.
+  _overflow;
+  /**
+   * @param path - The SQLite file
+   * @param options.now - The clock, in ms since the epoch
+   */
+  constructor(path, options) {
+    const capacity = options?.capacity ?? DEFAULT_REPLAY_CACHE_CAPACITY;
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new RangeError(
+        `Replay cache capacity must be a positive integer, got ${capacity}`
+      );
+    }
+    this.capacity = capacity;
+    this._path = path;
+    this._now = options?.now ?? (() => Date.now());
+    this._overflow = new EnvelopeReplayCache({
+      capacity: 1e4,
+      ttlMs: 2 * MAX_ENVELOPE_AGE * 1e3,
+      now: this._now
+    });
+  }
+  /** Open the file now, rather than on first use. */
+  async open() {
+    await this._open();
+  }
+  /**
+   * Return true if the envelope must be dropped as a replay. Otherwise record
+   * the pair and return false.
+   *
+   * @param signedAt - The envelope's signed time, in ms since the epoch. It
+   *   matters only when the cache is full.
+   */
+  async seenOrRecord(fromAddress, messageId, signedAt) {
+    const db = await this._open();
+    const now = this._now();
+    if (now - this._lastPurge >= PURGE_INTERVAL_MS) this._purge(db);
+    if (this._overflow.has(fromAddress, messageId)) return true;
+    if (this._count < this.capacity) {
+      const { changes } = db.prepare(
+        "INSERT OR IGNORE INTO seen_envelopes (from_address, message_id, seen_at) VALUES (?, ?, ?)"
+      ).run(fromAddress, messageId, now / 1e3);
+      if (changes === 0) return true;
+      this._count += 1;
+      return false;
+    }
+    const known = db.prepare(
+      "SELECT 1 FROM seen_envelopes WHERE from_address = ? AND message_id = ?"
+    ).get(fromAddress, messageId);
+    if (known !== void 0) return true;
+    if (Math.abs(now - signedAt) <= MAX_ENVELOPE_AGE * 1e3) {
+      return this._overflow.seenOrRecord(fromAddress, messageId);
+    }
+    log.warn(
+      `Replay cache full (${this._count} ids); refused envelope ${messageId} from ${fromAddress} signed ${Math.round((now - signedAt) / 1e3)}s ago`
+    );
+    return true;
+  }
+  /** When this cache file was first created, in ms since the epoch. */
+  async createdAt() {
+    await this._open();
+    return this._createdAt;
+  }
+  /** True if an envelope signed at `signedAt` (ms) predates this cache. */
+  async signedBeforeCache(signedAt) {
+    return signedAt < await this.createdAt();
+  }
+  /** Number of ids currently held on disk. */
+  async count() {
+    const db = await this._open();
+    return this._countRows(db);
+  }
+  /** Close the file; the next call opens it again. */
+  async close() {
+    await this._opening?.catch(() => void 0);
+    this._db?.close();
+    this._db = null;
+  }
+  _open() {
+    if (this._db !== null) return Promise.resolve(this._db);
+    this._opening ??= this._connect().finally(() => {
+      this._opening = null;
+    });
+    return this._opening;
+  }
+  async _connect() {
+    (0, import_node_fs4.mkdirSync)((0, import_node_path4.dirname)(this._path), { recursive: true });
+    const db = new import_better_sqlite32.default(this._path, { timeout: 3e4 });
+    try {
+      await enableWal(db);
+      db.exec(SCHEMA);
+      db.prepare(
+        "INSERT OR IGNORE INTO replay_meta (key, value) VALUES ('created_at', ?)"
+      ).run(String(this._now() / 1e3));
+      const row = db.prepare("SELECT value FROM replay_meta WHERE key = 'created_at'").get();
+      this._createdAt = Number(row.value) * 1e3;
+      this._purge(db);
+    } catch (err) {
+      db.close();
+      throw err;
+    }
+    this._db = db;
+    return db;
+  }
+  _purge(db) {
+    const now = this._now();
+    db.prepare("DELETE FROM seen_envelopes WHERE seen_at < ?").run(
+      now / 1e3 - RETENTION_SECONDS
+    );
+    this._count = this._countRows(db);
+    this._lastPurge = now;
+  }
+  _countRows(db) {
+    const row = db.prepare("SELECT COUNT(*) AS n FROM seen_envelopes").get();
+    return row.n;
+  }
+};
+
 // src/sdk/agent.ts
+var RELAY_NO_MEMORY_MS = 6e4;
+function replayCacheCapacityFromEnv() {
+  const raw = process.env["UAM_REPLAY_CACHE_CAPACITY"];
+  if (raw === void 0 || raw === "") {
+    return DEFAULT_REPLAY_CACHE_CAPACITY;
+  }
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    log.warn(
+      `Ignoring invalid UAM_REPLAY_CACHE_CAPACITY=${JSON.stringify(raw)}; using ${DEFAULT_REPLAY_CACHE_CAPACITY}`
+    );
+    return DEFAULT_REPLAY_CACHE_CAPACITY;
+  }
+  return n;
+}
 var Agent = class {
   /** @internal */
   _config;
@@ -1640,6 +2345,23 @@ var Agent = class {
   _contactBook;
   /** @internal */
   _handshake;
+  /**
+   * @internal Wall clock in ms since the epoch, used by the inbound
+   * freshness/expiry checks and the replay cache. Replaceable in tests.
+   */
+  _clock = () => Date.now();
+  /**
+   * @internal Inbound replay cache, keyed by (from address, message id).
+   * Kept on disk under the data dir, so it outlives restarts and is shared by
+   * every process using it; capacity from UAM_REPLAY_CACHE_CAPACITY.
+   */
+  _replayCache;
+  /** Whether our relay has said it writes relay_meta. */
+  _relayStamps = false;
+  /** Until when, by _monotonic, to take the relay's last no as still true. */
+  _relayNoUntil = 0;
+  /** @internal Monotonic clock in ms. Replaceable in tests. */
+  _monotonic = () => performance.now();
   /**
    * Create an Agent. No I/O happens here -- call connect() to initialize.
    */
@@ -1661,6 +2383,13 @@ var Agent = class {
       this._contactBook,
       this._config.trustPolicy
     );
+    this._replayCache = new PersistentReplayCache(
+      (0, import_node_path5.join)(this._config.dataDir, "replay", "replay.db"),
+      {
+        capacity: replayCacheCapacityFromEnv(),
+        now: () => this._clock()
+      }
+    );
   }
   // -- Properties ----------------------------------------------------------
   /** The agent's full UAM address (e.g., 'myagent::youam.network'). */
@@ -1674,7 +2403,7 @@ var Agent = class {
   }
   /** UAM SDK version. */
   get version() {
-    return "0.1.0";
+    return SDK_VERSION;
   }
   /** The agent's public key (base64-encoded Ed25519 verify key). */
   get publicKey() {
@@ -1711,10 +2440,19 @@ var Agent = class {
     }
     await sodiumReady;
     this._keyManager.loadOrGenerate(this._config.name);
-    const storedToken = this._keyManager.loadToken(this._config.name);
+    try {
+      await this._replayCache.open();
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      log.warn(`Could not open the replay cache: ${reason}`);
+    }
+    const storedToken = this._keyManager.loadToken(
+      this._config.name,
+      this._config.relayUrl
+    );
     if (storedToken) {
       this._token = storedToken;
-      this._address = `${this._config.name}::${this._config.relayDomain}`;
+      this._useAddress(await this._storedAddress());
     } else if (this._autoRegister) {
       await this._registerWithRelay();
     } else {
@@ -1737,6 +2475,7 @@ var Agent = class {
    */
   async close() {
     this._contactBook.close();
+    await this._replayCache.close();
     if (this._transport) {
       await this._transport.disconnect();
     }
@@ -1744,7 +2483,12 @@ var Agent = class {
   }
   // -- Messaging -----------------------------------------------------------
   /**
-   * Send an encrypted, signed message. Returns the message_id.
+   * Send an encrypted, signed message.
+   *
+   * Returns the message id with what the relay did with it: `status`
+   * "pending" means the recipient only takes approved contacts, and the
+   * message was not kept (don't resend it). `delivered` is true only when
+   * the relay says the recipient has it.
    */
   async send(toAddress, message, options) {
     await this._ensureConnected();
@@ -1757,7 +2501,8 @@ var Agent = class {
       }
     }
     const recipientVk = await this._resolvePublicKey(toAddress);
-    if (!this._contactBook.isKnown(toAddress)) {
+    const trustState = this._contactBook.getTrustState(toAddress);
+    if (trustState !== "pinned" && trustState !== "verified" && trustState !== "trusted" && trustState !== "handshake-sent") {
       await this._initiateHandshake(toAddress, recipientVk);
     }
     const envelope = await createEnvelope(
@@ -1775,20 +2520,29 @@ var Agent = class {
     );
     const wire = toWireDict(envelope);
     const relayUrls = await this._getRelayUrls(toAddress);
+    let answer;
     if (relayUrls !== null && relayUrls.length === 1 && relayUrls[0] === this._config.relayUrl) {
-      await this._transport.send(wire);
+      answer = await this._transport.send(wire);
     } else if (relayUrls !== null && relayUrls.length > 0) {
-      await this._trySendWithFailover(wire, relayUrls);
+      answer = await this._trySendWithFailover(wire, relayUrls);
     } else {
-      await this._transport.send(wire);
+      answer = await this._transport.send(wire);
     }
-    return envelope.messageId;
+    const status = sendStatus(answer);
+    return {
+      messageId: envelope.messageId,
+      status,
+      delivered: status === "delivered"
+    };
   }
   /**
    * Retrieve, decrypt, and verify pending messages.
    *
    * Returns a list of ReceivedMessage data objects.
-   * Silently drops messages with invalid signatures or decryption errors.
+   * Drops messages with invalid signatures or decryption errors. A message
+   * that fails processing for any other reason (malformed envelope, bad
+   * handshake payload, ...) is logged and dropped; it never aborts the
+   * rest of the batch.
    */
   async inbox(limit = 50) {
     await this._ensureConnected();
@@ -1796,7 +2550,15 @@ var Agent = class {
     const rawMessages = await this._transport.receive(limit);
     const result = [];
     for (const raw of rawMessages) {
-      const msg = await this._processInbound(raw);
+      let msg;
+      try {
+        msg = await this._processInbound(raw);
+      } catch (err) {
+        log.warn(
+          `Dropping inbound message ${String(raw["message_id"])} from ${String(raw["from"])}: ${err instanceof Error ? err.message : String(err)}`
+        );
+        continue;
+      }
       if (msg !== null) {
         result.push(msg);
         await this._sendReadReceipt(msg);
@@ -1816,42 +2578,43 @@ var Agent = class {
    * Adds the sender to contacts with trust_source='explicit-approval'
    * and sends handshake.accept back.
    */
-  async approve(address) {
+  async approve(address2) {
     await this._ensureConnected();
     const pendingList = this._contactBook.getPending();
-    const entry = pendingList.find((p) => p.address === address);
+    const entry = pendingList.find((p) => p.address === address2);
     if (!entry) {
-      throw new UAMError(`No pending handshake from ${address}`);
+      throw new UAMError(`No pending handshake from ${address2}`);
     }
     const cardDict = JSON.parse(entry.contactCard);
     const card = contactCardFromDict(cardDict);
     verifyContactCard(card);
+    const senderVk = deserializeVerifyKey(card.publicKey);
+    bindCardToEnvelope(card, { fromAddress: address2 }, senderVk);
     this._contactBook.addContact(card.address, card.publicKey, {
       displayName: card.displayName,
       trustState: "trusted",
       trustSource: "explicit-approval"
     });
-    this._contactBook.removePending(address);
-    const senderVk = deserializeVerifyKey(card.publicKey);
-    await this._handshake._sendAccept(this, address, senderVk);
+    this._contactBook.removePending(address2);
+    await this._handshake._sendAccept(this, address2, senderVk);
   }
   /**
    * Deny a pending handshake request.
    *
    * Removes the entry from pending and sends handshake.deny.
    */
-  async deny(address) {
+  async deny(address2) {
     await this._ensureConnected();
     const pendingList = this._contactBook.getPending();
-    const entry = pendingList.find((p) => p.address === address);
+    const entry = pendingList.find((p) => p.address === address2);
     if (!entry) {
-      throw new UAMError(`No pending handshake from ${address}`);
+      throw new UAMError(`No pending handshake from ${address2}`);
     }
     const cardDict = JSON.parse(entry.contactCard);
     const card = contactCardFromDict(cardDict);
     const senderVk = deserializeVerifyKey(card.publicKey);
-    this._contactBook.removePending(address);
-    await this._handshake._sendDeny(this, address, senderVk);
+    this._contactBook.removePending(address2);
+    await this._handshake._sendDeny(this, address2, senderVk);
   }
   /**
    * Block an address or domain pattern (HAND-04).
@@ -1877,7 +2640,7 @@ var Agent = class {
    *
    * Returns `true` if verified, `false` on timeout.
    */
-  async verifyDomain(domain, options) {
+  async verifyDomain(domain2, options) {
     const { generateTxtRecord: generateTxtRecord2 } = await Promise.resolve().then(() => (init_dns_verifier(), dns_verifier_exports));
     await this._ensureConnected();
     const timeout = options?.timeout ?? 3e5;
@@ -1898,7 +2661,7 @@ var Agent = class {
               "Content-Type": "application/json",
               Authorization: `Bearer ${this._token}`
             },
-            body: JSON.stringify({ domain }),
+            body: JSON.stringify({ domain: domain2 }),
             signal: AbortSignal.timeout(3e4)
           }
         );
@@ -1951,7 +2714,7 @@ var Agent = class {
         if (!resp.ok) {
           throw new Error(`HTTP ${resp.status}`);
         }
-        return;
+        return await readAnswer(resp);
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
       }
@@ -1969,6 +2732,10 @@ var Agent = class {
   /**
    * Resolve a recipient's public key, checking contact book first.
    *
+   * Pure lookup: never writes to the contact book. The contact row is
+   * created by _initiateHandshake (as "handshake-sent") once the request
+   * has gone out, giving the lifecycle no row -> handshake-sent -> pinned.
+   *
    * TOFU-01: Known contacts always use stored key (zero network I/O).
    * TOFU-03: Race-condition double-check after network resolve.
    * Raises KeyPinningError if a pinned contact's key doesn't match.
@@ -1992,9 +2759,6 @@ var Agent = class {
         );
       }
     }
-    this._contactBook.addContact(toAddress, resolvedPkStr, {
-      trustState: "provisional"
-    });
     return deserializeVerifyKey(resolvedPkStr);
   }
   async _initiateHandshake(toAddress, recipientVk) {
@@ -2041,6 +2805,9 @@ var Agent = class {
       }
       throw err;
     }
+    if (!await this._passesInboundChecks(envelope, raw)) {
+      return null;
+    }
     if (envelope.type === "handshake.request" /* HANDSHAKE_REQUEST */ || envelope.type === "handshake.accept" /* HANDSHAKE_ACCEPT */ || envelope.type === "handshake.deny" /* HANDSHAKE_DENY */) {
       return this._handshake.handleInbound(this, envelope, senderVk);
     }
@@ -2075,6 +2842,102 @@ var Agent = class {
       verified: true
     });
   }
+  /**
+   * Recipient, freshness, expiry and replay checks for a signature-verified
+   * inbound envelope. Returns false (and logs) when it must be dropped.
+   * Matches the Python SDK's _process_inbound checks.
+   */
+  async _passesInboundChecks(envelope, raw) {
+    const id = envelope.messageId;
+    const from = envelope.fromAddress;
+    if (this._address !== null && envelope.toAddress !== this._address) {
+      log.warn(
+        `Dropped envelope ${id} from ${from} addressed to ${envelope.toAddress} (we are ${this._address})`
+      );
+      return false;
+    }
+    const now = this._clock();
+    const ts = Date.parse(envelope.timestamp);
+    if (Number.isNaN(ts)) {
+      log.warn(
+        `Dropped envelope ${id} from ${from} with malformed timestamp ` + JSON.stringify(envelope.timestamp)
+      );
+      return false;
+    }
+    const ageSeconds = Math.abs(now - ts) / 1e3;
+    if (ageSeconds > MAX_ENVELOPE_AGE && !await this._wasStored(raw, envelope.toAddress, ts, now)) {
+      log.info(
+        `Dropped stale envelope ${id} from ${from} (age=${Math.round(ageSeconds)}s > ${MAX_ENVELOPE_AGE}s)`
+      );
+      return false;
+    }
+    if (envelope.expires !== void 0 && envelope.expires !== null) {
+      const exp = Date.parse(envelope.expires);
+      if (Number.isNaN(exp)) {
+        log.warn(
+          `Dropped envelope ${id} from ${from} with malformed expires ` + JSON.stringify(envelope.expires)
+        );
+        return false;
+      }
+      if (now > exp) {
+        log.info(
+          `Dropped expired envelope ${id} from ${from} (expires=${envelope.expires})`
+        );
+        return false;
+      }
+    }
+    if (await this._replayCache.seenOrRecord(from, id, ts)) {
+      log.info(`Dropped replayed envelope ${id} from ${from}`);
+      return false;
+    }
+    return true;
+  }
+  /** True if a message too old to be live is stored mail, not a replay. */
+  async _wasStored(raw, toAddress, signedAt, now) {
+    const relayDomain = toAddress.split("::").pop();
+    if (!relayVouches(raw, signedAt, now, relayDomain)) return false;
+    if (await this._replayCache.signedBeforeCache(signedAt)) return false;
+    return this._relayStampsMail();
+  }
+  /**
+   * True if our relay writes relay_meta, so a sender can't have.
+   *
+   * Asked only when a stale message carries a stamp. A yes is remembered for
+   * good, a no for RELAY_NO_MEMORY_MS: a relay can be upgraded while this
+   * agent runs. A failed lookup isn't remembered, because the relay has
+   * already marked this mail delivered and the next message should get a
+   * real answer.
+   */
+  async _relayStampsMail() {
+    if (this._relayStamps) return true;
+    if (this._monotonic() < this._relayNoUntil) return false;
+    try {
+      const features = await this._fetchRelayFeatures();
+      this._relayStamps = features.includes(RELAY_META_FEATURE);
+      if (!this._relayStamps) {
+        this._relayNoUntil = this._monotonic() + RELAY_NO_MEMORY_MS;
+      }
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      log.warn(`Cannot read relay features: ${reason}`);
+    }
+    return this._relayStamps;
+  }
+  /** The relay's features; a body that doesn't list any is an empty list. */
+  async _fetchRelayFeatures() {
+    const resp = await fetch(`${this._config.relayUrl}/api/v1/versions`, {
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!resp.ok) throw new UAMError(`Relay answered ${resp.status}`);
+    const body = await resp.text();
+    let data;
+    try {
+      data = JSON.parse(body);
+    } catch {
+      return [];
+    }
+    return Array.isArray(data?.features) ? data.features : [];
+  }
   /**
    * Sweep expired pending handshakes and send receipt.failed (HAND-03).
    */
@@ -2127,7 +2990,8 @@ var Agent = class {
         "receipt.read" /* RECEIPT_READ */,
         new TextEncoder().encode(receiptPayload),
         this._keyManager.signingKey,
-        senderVk
+        senderVk,
+        { replyTo: msg.messageId }
       );
       const wire = toWireDict(envelope);
       await this._transport.send(wire);
@@ -2137,26 +3001,25 @@ var Agent = class {
   /**
    * Register with the relay server.
    *
-   * Calls POST /api/v1/register with agent name and public key.
-   * Stores the returned API key on disk.
+   * Calls POST /api/v1/register with agent name and public key. If the
+   * address exists (409), repeats it with a proof that this agent holds the
+   * key. Stores the returned API key on disk.
    */
   async _registerWithRelay() {
-    const publicKeyStr = serializeVerifyKey(this._keyManager.verifyKey);
-    const resp = await fetch(
-      `${this._config.relayUrl}/api/v1/register`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          agent_name: this._config.name,
-          public_key: publicKeyStr
-        })
-      }
-    );
+    const body = {
+      agent_name: this._config.name,
+      public_key: serializeVerifyKey(this._keyManager.verifyKey)
+    };
+    let resp = await this._postRegistration(body);
     if (resp.status === 409) {
-      throw new UAMError(
-        `Address already registered with a different key: ${this._config.name}::${this._config.relayDomain}`
-      );
+      const address3 = await this._addressOnRelay();
+      resp = await this._postRegistration({
+        ...body,
+        proof: this._registrationProof(address3)
+      });
+      if (resp.status === 409 || resp.status === 403) {
+        throw this._ownershipNotProven(address3);
+      }
     }
     if (!resp.ok) {
       const text = await resp.text();
@@ -2165,22 +3028,140 @@ var Agent = class {
       );
     }
     const data = await resp.json();
-    this._address = data["address"];
+    const address2 = data["address"];
+    this._useAddress(address2);
     this._token = data["token"];
-    this._keyManager.saveToken(this._config.name, this._token);
+    const { name } = this._config;
+    const token = this._token;
+    this._tryToSave("token", () => this._keyManager.saveToken(name, token));
+    this._saveAddress(address2);
+  }
+  /** This agent's address on the relay, for signing a proof. */
+  async _addressOnRelay() {
+    const { name, explicitRelayDomain, relayDomain, relayUrl } = this._config;
+    if (explicitRelayDomain !== null) return `${name}::${explicitRelayDomain}`;
+    const domain2 = await this._fetchRelayDomain();
+    if (domain2 === null) return `${name}::${relayDomain}`;
+    if (!this._relayMayUse(domain2)) {
+      throw new UAMError(
+        `The relay at ${relayUrl} says its domain is ${domain2}. Pass the domain option as ${JSON.stringify(domain2)} if that is right.`
+      );
+    }
+    return `${name}::${domain2}`;
+  }
+  /**
+   * True if the relay's URL fits `domain`, so a proof can be signed for it.
+   *
+   * A proof names an address on one relay, so it is only signed for a domain
+   * this URL belongs to. A relay on this machine may use any domain.
+   */
+  _relayMayUse(domain2) {
+    let host;
+    try {
+      host = new URL(this._config.relayUrl).hostname.toLowerCase();
+    } catch {
+      return false;
+    }
+    const wanted = domain2.toLowerCase();
+    return host === wanted || host.endsWith(`.${wanted}`) || host === "localhost" || host === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(host);
+  }
+  _postRegistration(body) {
+    return fetch(`${this._config.relayUrl}/api/v1/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+  }
+  /**
+   * Sign a statement that this agent holds the key for `address`.
+   *
+   * The signed string must stay byte-identical to the Python SDK's.
+   */
+  _registrationProof(address2) {
+    const timestamp = utcTimestamp();
+    const signature = signMessage(
+      new TextEncoder().encode(`uam-register-v1
+${address2}
+${timestamp}`),
+      this._keyManager.signingKey
+    );
+    return { timestamp, signature };
+  }
+  _ownershipNotProven(address2) {
+    return new UAMError(
+      `Address already registered, and this key could not prove ownership: ` + address2
+    );
+  }
+  /** Remember `address` for this relay, if the key folder allows it. */
+  _saveAddress(address2) {
+    const { name, relayUrl } = this._config;
+    this._tryToSave(
+      "address",
+      () => this._keyManager.saveAddress(name, address2, relayUrl)
+    );
+  }
+  /** Saving is best effort: a key folder we can't write doesn't stop us. */
+  _tryToSave(what, save) {
+    try {
+      save();
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      log.warn(`Could not save the ${what}: ${reason}`);
+    }
+  }
+  /** Take `address` as ours; its domain is this relay's real domain. */
+  _useAddress(address2) {
+    this._address = address2;
+    const domain2 = parseAddress(address2).domain;
+    this._config.relayDomain = domain2;
+    if (this._resolver instanceof SmartResolver) {
+      this._resolver.relayDomain = domain2;
+    }
+  }
+  /**
+   * The address the stored token belongs to.
+   *
+   * An explicit domain settles it. Otherwise the relay chooses the domain,
+   * and it need not be the relay's hostname: use the address saved for this
+   * relay, or ask the relay once and keep the answer.
+   */
+  async _storedAddress() {
+    const { name, explicitRelayDomain } = this._config;
+    if (explicitRelayDomain !== null) return `${name}::${explicitRelayDomain}`;
+    const saved = this._keyManager.loadAddress(name, this._config.relayUrl);
+    if (saved) return saved;
+    const domain2 = await this._fetchRelayDomain();
+    if (domain2 === null) return `${name}::${this._config.relayDomain}`;
+    const address2 = `${name}::${domain2}`;
+    this._saveAddress(address2);
+    return address2;
+  }
+  /** Ask the relay for its domain; null if it cannot say. */
+  async _fetchRelayDomain() {
+    const url = `${this._config.relayUrl}/.well-known/uam-relay.json`;
+    try {
+      const resp = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+      if (!resp.ok) return null;
+      const data = await resp.json();
+      const domain2 = data["relay_domain"];
+      if (typeof domain2 !== "string" || domain2 === "") return null;
+      return parseAddress(`${this._config.name}::${domain2}`).domain;
+    } catch {
+      return null;
+    }
   }
 };
 
 // src/cli/helpers.ts
-var import_node_fs4 = require("fs");
-var import_node_path4 = require("path");
+var import_node_fs5 = require("fs");
+var import_node_path6 = require("path");
 var import_node_os4 = require("os");
 function findAgentName(keyDir) {
-  const dir = keyDir ?? (0, import_node_path4.join)(process.env["UAM_HOME"] ?? (0, import_node_path4.join)((0, import_node_os4.homedir)(), ".uam"), "keys");
-  if (!(0, import_node_fs4.existsSync)(dir)) {
+  const dir = keyDir ?? (0, import_node_path6.join)(process.env["UAM_HOME"] ?? (0, import_node_path6.join)((0, import_node_os4.homedir)(), ".uam"), "keys");
+  if (!(0, import_node_fs5.existsSync)(dir)) {
     return null;
   }
-  const keyFiles = (0, import_node_fs4.readdirSync)(dir).filter((f) => f.endsWith(".key")).sort();
+  const keyFiles = (0, import_node_fs5.readdirSync)(dir).filter((f) => f.endsWith(".key")).sort();
   if (keyFiles.length === 0) {
     return null;
   }
@@ -2200,21 +3181,21 @@ async function initCommand(options) {
   try {
     const cfg = new SDKConfig({ name: agentName, relayUrl: options.relay });
     const km = new KeyManager(cfg.keyDir);
-    const keyPath = (0, import_node_path5.join)(cfg.keyDir, `${agentName}.key`);
-    if ((0, import_node_fs5.existsSync)(keyPath)) {
+    const keyPath = (0, import_node_path7.join)(cfg.keyDir, `${agentName}.key`);
+    if ((0, import_node_fs6.existsSync)(keyPath)) {
       km.loadOrGenerate(agentName);
-      const address2 = `${agentName}::${cfg.relayDomain}`;
+      const address3 = km.loadAddress(agentName, cfg.relayUrl) ?? `${agentName}::${cfg.relayDomain}`;
       const fp2 = publicKeyFingerprint(km.verifyKey);
-      console.log(`Agent already initialized: ${address2}`);
+      console.log(`Agent already initialized: ${address3}`);
       console.log(`Fingerprint: ${fp2}`);
       return;
     }
     const agent = new Agent(agentName, { relay: options.relay });
     await agent.connect();
-    const address = agent.address;
+    const address2 = agent.address;
     const fp = publicKeyFingerprint(agent._keyManager.verifyKey);
     await agent.close();
-    console.log(`Initialized agent: ${address}`);
+    console.log(`Initialized agent: ${address2}`);
     console.log(`Fingerprint: ${fp}`);
   } catch (err) {
     cliError(`Error: ${err instanceof Error ? err.message : String(err)}`);
@@ -2222,7 +3203,7 @@ async function initCommand(options) {
 }
 
 // src/cli/commands/send.ts
-async function sendCommand(address, message, options) {
+async function sendCommand(address2, message, options) {
   const agentName = options.name ?? findAgentName();
   if (!agentName) {
     cliError("No agent initialized. Run `uam init` first.");
@@ -2230,9 +3211,12 @@ async function sendCommand(address, message, options) {
   try {
     const agent = new Agent(agentName);
     await agent.connect();
-    const msgId = await agent.send(address, message);
+    const result = await agent.send(address2, message);
     await agent.close();
-    console.log(`Message sent to ${address} (id: ${msgId})`);
+    console.log(`Message to ${address2}: ${result.status} (id: ${result.messageId})`);
+    if (result.status === "pending") {
+      console.log(pendingNote(address2));
+    }
   } catch (err) {
     cliError(`Error: ${err instanceof Error ? err.message : String(err)}`);
   }
@@ -2284,24 +3268,24 @@ async function cardCommand(options) {
 }
 
 // src/cli/commands/whoami.ts
-var import_node_fs6 = require("fs");
-var import_node_path6 = require("path");
+var import_node_fs7 = require("fs");
+var import_node_path8 = require("path");
 async function whoamiCommand(options) {
   const agentName = options.name ?? findAgentName();
   if (!agentName) {
     cliError("No agent initialized. Run `uam init` first.");
   }
   const cfg = new SDKConfig({ name: agentName });
-  const keyPath = (0, import_node_path6.join)(cfg.keyDir, `${agentName}.key`);
-  if (!(0, import_node_fs6.existsSync)(keyPath)) {
+  const keyPath = (0, import_node_path8.join)(cfg.keyDir, `${agentName}.key`);
+  if (!(0, import_node_fs7.existsSync)(keyPath)) {
     cliError("No agent initialized. Run `uam init` first.");
   }
   await sodiumReady;
   const km = new KeyManager(cfg.keyDir);
   km.loadOrGenerate(agentName);
-  const address = `${agentName}::${cfg.relayDomain}`;
+  const address2 = km.loadAddress(agentName, cfg.relayUrl) ?? `${agentName}::${cfg.relayDomain}`;
   const fp = publicKeyFingerprint(km.verifyKey);
-  console.log(`Address:     ${address}`);
+  console.log(`Address:     ${address2}`);
   console.log(`Fingerprint: ${fp}`);
   console.log(`Key file:    ${keyPath}`);
 }
@@ -2372,7 +3356,7 @@ async function pendingCommand(options) {
 }
 
 // src/cli/commands/approve.ts
-async function approveCommand(address, options) {
+async function approveCommand(address2, options) {
   const agentName = options.name ?? findAgentName();
   if (!agentName) {
     cliError("No agent initialized. Run `uam init` first.");
@@ -2380,16 +3364,16 @@ async function approveCommand(address, options) {
   try {
     const agent = new Agent(agentName);
     await agent.connect();
-    await agent.approve(address);
+    await agent.approve(address2);
     await agent.close();
-    console.log(`Approved: ${address}`);
+    console.log(`Approved: ${address2}`);
   } catch (err) {
     cliError(`Error: ${err instanceof Error ? err.message : err}`);
   }
 }
 
 // src/cli/commands/deny.ts
-async function denyCommand(address, options) {
+async function denyCommand(address2, options) {
   const agentName = options.name ?? findAgentName();
   if (!agentName) {
     cliError("No agent initialized. Run `uam init` first.");
@@ -2397,9 +3381,9 @@ async function denyCommand(address, options) {
   try {
     const agent = new Agent(agentName);
     await agent.connect();
-    await agent.deny(address);
+    await agent.deny(address2);
     await agent.close();
-    console.log(`Denied: ${address}`);
+    console.log(`Denied: ${address2}`);
   } catch (err) {
     cliError(`Error: ${err instanceof Error ? err.message : err}`);
   }
@@ -2441,21 +3425,21 @@ async function unblockCommand(pattern, options) {
 }
 
 // src/cli/commands/contact.ts
-async function contactFingerprintCommand(address, options) {
+async function contactFingerprintCommand(address2, options) {
   const agentName = options.name ?? findAgentName();
   const cfg = new SDKConfig({ name: agentName ?? "_probe" });
   const book = new ContactBook(cfg.dataDir);
   try {
     book.open();
-    const pkStr = book.getPublicKey(address);
+    const pkStr = book.getPublicKey(address2);
     book.close();
     if (pkStr === null) {
-      cliError(`Contact not found: ${address}`);
+      cliError(`Contact not found: ${address2}`);
     }
     const vk = deserializeVerifyKey(pkStr);
     const fp = publicKeyFingerprint(vk);
     const shortFp = fp.slice(0, 16);
-    console.log(`Address:     ${address}`);
+    console.log(`Address:     ${address2}`);
     console.log(`Fingerprint: ${shortFp}`);
     console.log(`Full:        ${fp}`);
   } catch (err) {
@@ -2465,43 +3449,43 @@ async function contactFingerprintCommand(address, options) {
     cliError(`Error: ${err instanceof Error ? err.message : err}`);
   }
 }
-async function contactVerifyCommand(address, options) {
+async function contactVerifyCommand(address2, options) {
   const agentName = options.name ?? findAgentName();
   const cfg = new SDKConfig({ name: agentName ?? "_probe" });
   const book = new ContactBook(cfg.dataDir);
   try {
     book.open();
-    const pkStr = book.getPublicKey(address);
+    const pkStr = book.getPublicKey(address2);
     if (pkStr === null) {
       book.close();
-      cliError(`Contact not found: ${address}`);
+      cliError(`Contact not found: ${address2}`);
     }
     const vk = deserializeVerifyKey(pkStr);
     const fp = publicKeyFingerprint(vk);
-    console.log(`Fingerprint for ${address}: ${fp.slice(0, 16)}`);
-    book.addContact(address, pkStr, {
+    console.log(`Fingerprint for ${address2}: ${fp.slice(0, 16)}`);
+    book.addContact(address2, pkStr, {
       trustState: "verified",
       trustSource: "manual-verify"
     });
     book.close();
-    console.log(`Contact ${address} verified. Trust state: verified`);
+    console.log(`Contact ${address2} verified. Trust state: verified`);
   } catch (err) {
     cliError(`Error: ${err instanceof Error ? err.message : err}`);
   }
 }
-async function contactRemoveCommand(address, options) {
+async function contactRemoveCommand(address2, options) {
   const agentName = options.name ?? findAgentName();
   const cfg = new SDKConfig({ name: agentName ?? "_probe" });
   const book = new ContactBook(cfg.dataDir);
   try {
     book.open();
-    const removed = book.removeContact(address);
+    const removed = book.removeContact(address2);
     book.close();
     if (!removed) {
-      cliError(`Contact not found: ${address}`);
+      cliError(`Contact not found: ${address2}`);
     }
     console.log(
-      `Contact ${address} removed. Future messages will re-resolve the public key.`
+      `Contact ${address2} removed. Future messages will re-resolve the public key.`
     );
   } catch (err) {
     cliError(`Error: ${err instanceof Error ? err.message : err}`);
@@ -2510,7 +3494,7 @@ async function contactRemoveCommand(address, options) {
 
 // src/cli/commands/verify-domain.ts
 init_dns_verifier();
-async function verifyDomainCommand(domain, options) {
+async function verifyDomainCommand(domain2, options) {
   const agentName = options.name ?? findAgentName();
   if (!agentName) {
     cliError("No agent initialized. Run `uam init` first.");
@@ -2523,27 +3507,27 @@ async function verifyDomainCommand(domain, options) {
     const pubkey = agent.publicKey;
     const relayUrl = agent._config.relayUrl;
     const txtValue = generateTxtRecord(pubkey, relayUrl);
-    console.log(`Add this DNS TXT record to verify ${domain}:`);
+    console.log(`Add this DNS TXT record to verify ${domain2}:`);
     console.log();
-    console.log(`  Host:  _uam.${domain}`);
+    console.log(`  Host:  _uam.${domain2}`);
     console.log(`  Type:  TXT`);
     console.log(`  Value: ${txtValue}`);
     console.log();
     console.log(`Or serve this HTTPS fallback:`);
     console.log();
-    console.log(`  URL: https://${domain}/.well-known/uam.json`);
+    console.log(`  URL: https://${domain2}/.well-known/uam.json`);
     console.log();
     console.log(`See documentation for .well-known/uam.json format.`);
     console.log();
     console.log("Polling for verification...");
-    const verified = await agent.verifyDomain(domain, {
+    const verified = await agent.verifyDomain(domain2, {
       timeout: timeout * 1e3,
       pollInterval: pollInterval * 1e3
     });
     await agent.close();
     if (verified) {
       console.log(
-        `Verified! ${agent.address} is now Tier 2 via ${domain}.`
+        `Domain checked by ${agent.address.split("::")[1] ?? "your relay"}: ${agent.address} is now Tier 2 via ${domain2}.`
       );
     } else {
       console.log(
@@ -2557,7 +3541,7 @@ async function verifyDomainCommand(domain, options) {
 
 // src/cli/index.ts
 var program = new import_commander.Command();
-program.name("uam").description("Universal Agent Messaging CLI").version("0.1.0");
+program.name("uam").description("Universal Agent Messaging CLI").version(SDK_VERSION);
 program.option("-n, --name <name>", "Agent name (auto-detected from ~/.uam/keys/)");
 program.command("init").description("Initialize a new agent: generate keys and register with relay").option("-n, --name <name>", "Agent name").option("-r, --relay <url>", "Relay URL (default: relay.youam.network)").action(async (opts) => {
   const globalName = program.opts().name;
@@ -2566,9 +3550,9 @@ program.command("init").description("Initialize a new agent: generate keys and r
     relay: opts.relay
   });
 });
-program.command("send <address> <message>").description("Send a message to another agent").action(async (address, message) => {
+program.command("send <address> <message>").description("Send a message to another agent").action(async (address2, message) => {
   const globalName = program.opts().name;
-  await sendCommand(address, message, { name: globalName });
+  await sendCommand(address2, message, { name: globalName });
 });
 program.command("inbox").description("Check your inbox for pending messages").option("-l, --limit <number>", "Max messages to retrieve", "20").action(async (opts) => {
   const globalName = program.opts().name;
@@ -2590,21 +3574,21 @@ program.command("contacts").description("List known contacts from the local cont
   await contactsCommand({ name: globalName });
 });
 var contactCmd = program.command("contact").description("Contact management commands (fingerprint, verify, remove)");
-contactCmd.command("fingerprint <address>").description("Display the fingerprint for a known contact's public key").action(async (address) => {
+contactCmd.command("fingerprint <address>").description("Display the fingerprint for a known contact's public key").action(async (address2) => {
   const globalName = program.opts().name;
-  await contactFingerprintCommand(address, { name: globalName });
+  await contactFingerprintCommand(address2, { name: globalName });
 });
-contactCmd.command("verify <address>").description("Manually verify a contact, upgrading trust state to verified").option("-y, --yes", "Skip confirmation prompt").action(async (address, opts) => {
+contactCmd.command("verify <address>").description("Manually verify a contact, upgrading trust state to verified").option("-y, --yes", "Skip confirmation prompt").action(async (address2, opts) => {
   const globalName = program.opts().name;
-  await contactVerifyCommand(address, { name: globalName, yes: opts.yes });
+  await contactVerifyCommand(address2, { name: globalName, yes: opts.yes });
 });
-contactCmd.command("remove <address>").description("Remove a contact from the contact book").action(async (address) => {
+contactCmd.command("remove <address>").description("Remove a contact from the contact book").action(async (address2) => {
   const globalName = program.opts().name;
-  await contactRemoveCommand(address, { name: globalName });
+  await contactRemoveCommand(address2, { name: globalName });
 });
-program.command("verify-domain <domain>").description("Verify domain ownership for Tier 2 DNS-verified status").option("-t, --timeout <seconds>", "Polling timeout in seconds", "300").option("--poll-interval <seconds>", "Polling interval in seconds", "10").action(async (domain, opts) => {
+program.command("verify-domain <domain>").description("Verify domain ownership for Tier 2 DNS-verified status").option("-t, --timeout <seconds>", "Polling timeout in seconds", "300").option("--poll-interval <seconds>", "Polling interval in seconds", "10").action(async (domain2, opts) => {
   const globalName = program.opts().name;
-  await verifyDomainCommand(domain, {
+  await verifyDomainCommand(domain2, {
     name: globalName,
     timeout: parseInt(opts.timeout, 10),
     pollInterval: parseInt(opts.pollInterval, 10)
@@ -2614,13 +3598,13 @@ program.command("pending").description("List pending handshake requests awaiting
   const globalName = program.opts().name;
   await pendingCommand({ name: globalName });
 });
-program.command("approve <address>").description("Approve a pending handshake request").action(async (address) => {
+program.command("approve <address>").description("Approve a pending handshake request").action(async (address2) => {
   const globalName = program.opts().name;
-  await approveCommand(address, { name: globalName });
+  await approveCommand(address2, { name: globalName });
 });
-program.command("deny <address>").description("Deny a pending handshake request").action(async (address) => {
+program.command("deny <address>").description("Deny a pending handshake request").action(async (address2) => {
   const globalName = program.opts().name;
-  await denyCommand(address, { name: globalName });
+  await denyCommand(address2, { name: globalName });
 });
 program.command("block <pattern>").description("Block an address or domain pattern (e.g., spammer::evil.com or *::evil.com)").action(async (pattern) => {
   const globalName = program.opts().name;