@youam/sdk 0.2.0 → 0.2.1

package/dist/cli/index.cjs

@@ -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.2.1";
+
 // 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");
 }
@@ -636,6 +640,9 @@ function verifyContactCard(card) {
 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 +659,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 +676,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 +780,54 @@ var KeyManager = class {
     (0, import_node_fs.writeFileSync)(tokenPath, token);
     this._setPermissions(tokenPath);
   }
+  /**
+   * Store the address `relayUrl` gave this agent.
+   */
+  saveAddress(name, address, 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, 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 address = saved?.address;
+      const savedRelay = saved?.relay_url;
+      if (typeof address !== "string" || typeof savedRelay !== "string") {
+        return null;
+      }
+      if (trimRelayUrl(savedRelay) !== trimRelayUrl(relayUrl)) return null;
+      parseAddress(address);
+      return address;
+    } 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 +838,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 +875,48 @@ 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/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;
@@ -936,11 +1037,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) {
     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(address);
+    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(address)}: 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 ${address} (key rotation)`
+      );
+    }
     const displayName = options?.displayName ?? null;
     const trustState = options?.trustState ?? "trusted";
     const trustSource = options?.trustSource ?? null;
@@ -1113,6 +1233,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 +1287,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 +1305,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 +1324,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 +1420,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";
@@ -1365,8 +1540,6 @@ 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) {
     const resp = await fetch(
@@ -1403,13 +1576,13 @@ var Tier2Resolver = class extends AddressResolver {
   }
 };
 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;
@@ -1417,7 +1590,7 @@ var SmartResolver = class extends AddressResolver {
   async resolvePublicKey(address, token, relayUrl) {
     const parsed = parseAddress(address);
     const domain = parsed.domain;
-    if (domain === this._relayDomain) {
+    if (domain === this.relayDomain) {
       return this._tier1.resolvePublicKey(address, token, relayUrl);
     }
     if (domain.includes(".")) {
@@ -1496,8 +1669,10 @@ 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 WebSocketTransport = class extends TransportBase {
   _url;
+  _token;
   _onMessage;
   _ws = null;
   _pending = [];
@@ -1506,9 +1681,16 @@ 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;
+  /** @internal How long a close waits, in ms. Replaceable in tests. */
+  _settleMs = SEND_SETTLE_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 +1711,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);
@@ -1547,6 +1736,7 @@ var WebSocketTransport = class extends TransportBase {
       throw new Error("WebSocket not connected");
     }
     this._ws.send(JSON.stringify(envelope));
+    this._unanswered += 1;
   }
   async receive(limit = 50) {
     const result = this._pending.slice(0, limit);
@@ -1556,11 +1746,32 @@ 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;
+  }
+  _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 +1792,8 @@ var WebSocketTransport = class extends TransportBase {
       ws.on("close", () => {
         this._connected = false;
         this._ws = null;
+        this._unanswered = 0;
+        this._settled?.();
         if (!this._running) return;
         attempt += 1;
         const delay = Math.min(BASE_DELAY * Math.pow(2, attempt), MAX_DELAY);
@@ -1597,19 +1810,21 @@ 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();
+    } else if (msgType === "error" || "error" in msg) {
+      this._answered();
     }
   }
 };
@@ -1623,7 +1838,239 @@ function createTransport(config, token, address, 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 +2087,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 +2125,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 +2145,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 +2182,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 +2217,7 @@ var Agent = class {
    */
   async close() {
     this._contactBook.close();
+    await this._replayCache.close();
     if (this._transport) {
       await this._transport.disconnect();
     }
@@ -1757,7 +2238,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(
@@ -1788,7 +2270,10 @@ var Agent = class {
    * 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 +2281,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);
@@ -1826,13 +2319,14 @@ var Agent = class {
     const cardDict = JSON.parse(entry.contactCard);
     const card = contactCardFromDict(cardDict);
     verifyContactCard(card);
+    const senderVk = deserializeVerifyKey(card.publicKey);
+    bindCardToEnvelope(card, { fromAddress: address }, 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);
   }
   /**
@@ -1969,6 +2463,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 +2490,6 @@ var Agent = class {
         );
       }
     }
-    this._contactBook.addContact(toAddress, resolvedPkStr, {
-      trustState: "provisional"
-    });
     return deserializeVerifyKey(resolvedPkStr);
   }
   async _initiateHandshake(toAddress, recipientVk) {
@@ -2041,6 +2536,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 +2573,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 +2721,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 +2732,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 address2 = await this._addressOnRelay();
+      resp = await this._postRegistration({
+        ...body,
+        proof: this._registrationProof(address2)
+      });
+      if (resp.status === 409 || resp.status === 403) {
+        throw this._ownershipNotProven(address2);
+      }
     }
     if (!resp.ok) {
       const text = await resp.text();
@@ -2165,22 +2759,140 @@ var Agent = class {
       );
     }
     const data = await resp.json();
-    this._address = data["address"];
+    const address = data["address"];
+    this._useAddress(address);
     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(address);
+  }
+  /** 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 domain = await this._fetchRelayDomain();
+    if (domain === null) return `${name}::${relayDomain}`;
+    if (!this._relayMayUse(domain)) {
+      throw new UAMError(
+        `The relay at ${relayUrl} says its domain is ${domain}. Pass the domain option as ${JSON.stringify(domain)} if that is right.`
+      );
+    }
+    return `${name}::${domain}`;
+  }
+  /**
+   * 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(domain) {
+    let host;
+    try {
+      host = new URL(this._config.relayUrl).hostname.toLowerCase();
+    } catch {
+      return false;
+    }
+    const wanted = domain.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(address) {
+    const timestamp = utcTimestamp();
+    const signature = signMessage(
+      new TextEncoder().encode(`uam-register-v1
+${address}
+${timestamp}`),
+      this._keyManager.signingKey
+    );
+    return { timestamp, signature };
+  }
+  _ownershipNotProven(address) {
+    return new UAMError(
+      `Address already registered, and this key could not prove ownership: ` + address
+    );
+  }
+  /** Remember `address` for this relay, if the key folder allows it. */
+  _saveAddress(address) {
+    const { name, relayUrl } = this._config;
+    this._tryToSave(
+      "address",
+      () => this._keyManager.saveAddress(name, address, 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(address) {
+    this._address = address;
+    const domain = parseAddress(address).domain;
+    this._config.relayDomain = domain;
+    if (this._resolver instanceof SmartResolver) {
+      this._resolver.relayDomain = domain;
+    }
+  }
+  /**
+   * 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 domain = await this._fetchRelayDomain();
+    if (domain === null) return `${name}::${this._config.relayDomain}`;
+    const address = `${name}::${domain}`;
+    this._saveAddress(address);
+    return address;
+  }
+  /** 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 domain = data["relay_domain"];
+      if (typeof domain !== "string" || domain === "") return null;
+      return parseAddress(`${this._config.name}::${domain}`).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,10 +2912,10 @@ 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 address2 = km.loadAddress(agentName, cfg.relayUrl) ?? `${agentName}::${cfg.relayDomain}`;
       const fp2 = publicKeyFingerprint(km.verifyKey);
       console.log(`Agent already initialized: ${address2}`);
       console.log(`Fingerprint: ${fp2}`);
@@ -2284,22 +2996,22 @@ 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 address = km.loadAddress(agentName, cfg.relayUrl) ?? `${agentName}::${cfg.relayDomain}`;
   const fp = publicKeyFingerprint(km.verifyKey);
   console.log(`Address:     ${address}`);
   console.log(`Fingerprint: ${fp}`);
@@ -2557,7 +3269,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;