@youam/sdk 0.2.0 → 0.4.0

package/dist/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)
@@ -115,10 +115,19 @@ var init_dns_verifier = __esm({
 var index_exports = {};
 __export(index_exports, {
   Agent: () => Agent,
-  protocol: () => protocol_exports
+  ContactBook: () => ContactBook,
+  PENDING_NOTE: () => PENDING_NOTE,
+  SEND_STATUSES: () => SEND_STATUSES,
+  pendingNote: () => pendingNote,
+  protocol: () => protocol_exports,
+  supports: () => supports,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/sdk/agent.ts
+var import_node_path5 = require("path");
+
 // src/protocol/index.ts
 var protocol_exports = {};
 __export(protocol_exports, {
@@ -127,31 +136,43 @@ __export(protocol_exports, {
   EnvelopeTooLargeError: () => EnvelopeTooLargeError,
   InvalidAddressError: () => InvalidAddressError,
   InvalidContactCardError: () => InvalidContactCardError,
+  InvalidDidKeyError: () => InvalidDidKeyError,
   InvalidEnvelopeError: () => InvalidEnvelopeError,
   KeyPinningError: () => KeyPinningError,
+  MAX_ENVELOPE_AGE: () => MAX_ENVELOPE_AGE,
   MAX_ENVELOPE_SIZE: () => MAX_ENVELOPE_SIZE,
   MessageType: () => MessageType,
+  SendRefusedError: () => SendRefusedError,
   SignatureError: () => SignatureError,
   SignatureVerificationError: () => SignatureVerificationError,
+  SignedObjectError: () => SignedObjectError,
   UAMError: () => UAMError,
   UAM_VERSION: () => UAM_VERSION,
+  WebAuthnError: () => WebAuthnError,
+  approvalChallenge: () => approvalChallenge,
   b64Decode: () => b64Decode,
   b64Encode: () => b64Encode,
+  canonical: () => canonical,
   canonicalize: () => canonicalize,
   contactCardFromDict: () => contactCardFromDict,
   contactCardToDict: () => contactCardToDict,
   createContactCard: () => createContactCard,
   createEnvelope: () => createEnvelope,
+  credentialDid: () => credentialDid,
+  decodeDidKey: () => decodeDidKey,
   decryptPayload: () => decryptPayload,
   decryptPayloadAnonymous: () => decryptPayloadAnonymous,
   deserializeSigningKey: () => deserializeSigningKey,
   deserializeVerifyKey: () => deserializeVerifyKey,
+  encodeDidKey: () => encodeDidKey,
   encryptPayload: () => encryptPayload,
   encryptPayloadAnonymous: () => encryptPayloadAnonymous,
   fromWireDict: () => fromWireDict,
   generateKeypair: () => generateKeypair,
   generateNonce: () => generateNonce,
+  objectHash: () => objectHash,
   parseAddress: () => parseAddress,
+  parseBody: () => parseBody,
   publicKeyFingerprint: () => publicKeyFingerprint,
   serializeSigningKey: () => serializeSigningKey,
   serializeVerifyKey: () => serializeVerifyKey,
@@ -160,14 +181,18 @@ __export(protocol_exports, {
   toWireDict: () => toWireDict,
   utcTimestamp: () => utcTimestamp,
   validateEnvelopeSize: () => validateEnvelopeSize,
+  validateSignedObject: () => validate,
+  verifyAssertion: () => verifyAssertion,
   verifyContactCard: () => verifyContactCard,
   verifyEnvelope: () => verifyEnvelope,
+  verifyRegistration: () => verifyRegistration,
   verifySignature: () => verifySignature
 });
 
 // src/protocol/types.ts
 var UAM_VERSION = "0.1";
 var MAX_ENVELOPE_SIZE = 65536;
+var MAX_ENVELOPE_AGE = 300;
 var MessageType = /* @__PURE__ */ ((MessageType2) => {
   MessageType2["MESSAGE"] = "message";
   MessageType2["HANDSHAKE_REQUEST"] = "handshake.request";
@@ -255,6 +280,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])?)$/;
@@ -381,11 +418,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;
@@ -395,11 +432,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));
@@ -507,7 +544,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 */) {
@@ -526,7 +563,7 @@ async function createEnvelope(fromAddress, toAddress, messageType, payloadPlaint
     toAddress,
     timestamp,
     type: typeValue,
-    nonce,
+    nonce: nonce2,
     payload: encryptedPayload,
     signature: "",
     threadId: options?.threadId,
@@ -545,7 +582,7 @@ async function createEnvelope(fromAddress, toAddress, messageType, payloadPlaint
     toAddress,
     timestamp,
     type: typeValue,
-    nonce,
+    nonce: nonce2,
     payload: encryptedPayload,
     signature,
     threadId: options?.threadId,
@@ -637,8 +674,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);
@@ -648,7 +685,7 @@ async function createContactCard(address, displayName, relay, signingKey, option
   ];
   const tempCard = {
     version: UAM_VERSION,
-    address,
+    address: address2,
     displayName,
     description: options?.description,
     system: options?.system,
@@ -665,7 +702,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,
@@ -692,10 +729,786 @@ 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 b58encode(data) {
+  let n = 0n;
+  for (const byte of data) n = n << 8n | BigInt(byte);
+  let out = "";
+  while (n > 0n) {
+    out = B58[Number(n % 58n)] + out;
+    n /= 58n;
+  }
+  let zeros = 0;
+  while (zeros < data.length && data[zeros] === 0) zeros += 1;
+  return "1".repeat(zeros) + out;
+}
+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 encodeDidKey(kind, publicKey) {
+  if (!(kind in PREFIX)) throw new InvalidDidKeyError(`unsupported key type: ${kind}`);
+  checkKey(kind, publicKey);
+  return "did:key:z" + b58encode(new Uint8Array([...PREFIX[kind], ...publicKey]));
+}
+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 GRANT_MAX_DAYS = 90;
+var INVITE_MAX_DAYS = 7;
+var SignedObjectError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "SignedObjectError";
+  }
+};
+var has = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+var Parser = class {
+  constructor(s) {
+    this.s = s;
+  }
+  i = 0;
+  fail(why) {
+    throw new SignedObjectError(`not JSON or outside the profile at ${this.i}: ${why}`);
+  }
+  ws() {
+    while (this.i < this.s.length && " 	\n\r".includes(this.s[this.i])) this.i += 1;
+  }
+  document() {
+    this.ws();
+    if (this.s[this.i] !== "{") this.fail("a body must be a JSON object");
+    const value = this.value();
+    this.ws();
+    if (this.i !== this.s.length) this.fail("trailing characters");
+    return value;
+  }
+  value() {
+    this.ws();
+    const c = this.s[this.i];
+    if (c === "{") return this.object();
+    if (c === "[") return this.array();
+    if (c === '"') return this.string();
+    if (c === "-" || c !== void 0 && c >= "0" && c <= "9") return this.number();
+    for (const [word, v] of [["true", true], ["false", false]]) {
+      if (this.s.startsWith(word, this.i)) {
+        this.i += word.length;
+        return v;
+      }
+    }
+    if (this.s.startsWith("null", this.i)) this.fail("null is not allowed");
+    return this.fail("unexpected character");
+  }
+  object() {
+    this.i += 1;
+    const out = /* @__PURE__ */ Object.create(null);
+    this.ws();
+    if (this.s[this.i] === "}") {
+      this.i += 1;
+      return out;
+    }
+    for (; ; ) {
+      this.ws();
+      if (this.s[this.i] !== '"') this.fail("expected a key");
+      const key = this.string();
+      if (has(out, key)) this.fail(`duplicate key: ${JSON.stringify(key)}`);
+      this.ws();
+      if (this.s[this.i] !== ":") this.fail("expected ':'");
+      this.i += 1;
+      Object.defineProperty(out, key, {
+        value: this.value(),
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+      this.ws();
+      if (this.s[this.i] === ",") {
+        this.i += 1;
+        continue;
+      }
+      if (this.s[this.i] === "}") {
+        this.i += 1;
+        return out;
+      }
+      this.fail("expected ',' or '}'");
+    }
+  }
+  array() {
+    this.i += 1;
+    const out = [];
+    this.ws();
+    if (this.s[this.i] === "]") {
+      this.i += 1;
+      return out;
+    }
+    for (; ; ) {
+      out.push(this.value());
+      this.ws();
+      if (this.s[this.i] === ",") {
+        this.i += 1;
+        continue;
+      }
+      if (this.s[this.i] === "]") {
+        this.i += 1;
+        return out;
+      }
+      this.fail("expected ',' or ']'");
+    }
+  }
+  string() {
+    this.i += 1;
+    let out = "";
+    for (; ; ) {
+      const c = this.s[this.i];
+      if (c === void 0) this.fail("unterminated string");
+      this.i += 1;
+      if (c === '"') break;
+      if (c === "\\") {
+        const e = this.s[this.i];
+        this.i += 1;
+        const simple = {
+          '"': '"',
+          "\\": "\\",
+          "/": "/",
+          b: "\b",
+          f: "\f",
+          n: "\n",
+          r: "\r",
+          t: "	"
+        };
+        if (e !== void 0 && has(simple, e)) {
+          out += simple[e];
+        } else if (e === "u") {
+          const hex = this.s.slice(this.i, this.i + 4);
+          if (!/^[0-9a-fA-F]{4}$/.test(hex)) this.fail("bad \\u escape");
+          out += String.fromCharCode(parseInt(hex, 16));
+          this.i += 4;
+        } else {
+          this.fail("bad escape");
+        }
+      } else {
+        if (c < " ") this.fail("control character in string");
+        out += c;
+      }
+    }
+    checkString(out);
+    return out;
+  }
+  number() {
+    const m = /^-?(0|[1-9][0-9]*)([.][0-9]+)?([eE][+-]?[0-9]+)?/.exec(this.s.slice(this.i));
+    if (!m) return this.fail("bad number");
+    const text = m[0];
+    if (m[2] !== void 0 || m[3] !== void 0) this.fail(`floats are not allowed: ${text}`);
+    if (text === "-0") this.fail("-0 is not allowed");
+    const big = BigInt(text);
+    if (big > BigInt(MAX_INT) || big < -BigInt(MAX_INT)) this.fail(`integer out of range: ${text}`);
+    this.i += text.length;
+    return Number(big);
+  }
+};
+function parseBody(text) {
+  let s;
+  if (typeof text === "string") {
+    s = text;
+  } else {
+    try {
+      s = new TextDecoder("utf-8", { fatal: true }).decode(text);
+    } catch {
+      throw new SignedObjectError("body is not UTF-8");
+    }
+  }
+  return new Parser(s).document();
+}
+function checkString(value) {
+  for (let i = 0; i < value.length; i += 1) {
+    const code = value.charCodeAt(i);
+    if (code < 32 || code > 126) {
+      throw new SignedObjectError("strings must be printable ASCII");
+    }
+  }
+}
+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;
+}
+function encode(value) {
+  if (value === true) return "true";
+  if (value === false) return "false";
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || Object.is(value, -0)) {
+      throw new SignedObjectError(`not an integer in range: ${value}`);
+    }
+    return String(value);
+  }
+  if (typeof value === "string") {
+    checkString(value);
+    return '"' + value.replace(/\\/g, "\\\\").replace(/"/g, '\\"') + '"';
+  }
+  if (Array.isArray(value)) return "[" + value.map(encode).join(",") + "]";
+  if (isPlainObject(value)) {
+    return "{" + Object.keys(value).sort().map((key) => {
+      checkString(key);
+      return encode(key) + ":" + encode(value[key]);
+    }).join(",") + "}";
+  }
+  if (value === null) throw new SignedObjectError("null is not allowed");
+  throw new SignedObjectError(`not allowed: ${typeof value}`);
+}
+function canonical(body) {
+  if (!isPlainObject(body)) throw new SignedObjectError("a body must be a JSON object");
+  return new TextEncoder().encode(encode(body));
+}
+function hashCanonical(body) {
+  return (0, import_node_crypto3.createHash)("sha256").update(`UAM-${String(body["type"])}-v1
+`).update(canonical(body)).digest("base64url");
+}
+function objectHash(body) {
+  validate(body);
+  return hashCanonical(body);
+}
+var TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})Z$/;
+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 string_ = (v, p) => {
+  if (typeof v !== "string" || v.length === 0) fail(p, "must be a non-empty string");
+};
+var label = (v, p) => {
+  string_(v, p);
+  if (v.length > 64) fail(p, "at most 64 characters");
+  if (v.includes('"')) fail(p, 'must not contain "');
+};
+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");
+function parseTime(value) {
+  const m = TIME_RE.exec(value);
+  if (!m) return null;
+  const [y, mo, d, h, mi, s] = m.slice(1).map(Number);
+  const t = Date.UTC(y, mo - 1, d, h, mi, s);
+  const back = new Date(t);
+  if (back.getUTCFullYear() !== y || back.getUTCMonth() !== mo - 1 || back.getUTCDate() !== d || back.getUTCHours() !== h || back.getUTCMinutes() !== mi || back.getUTCSeconds() !== s) {
+    return null;
+  }
+  return t;
+}
+var time = (v, p) => {
+  if (typeof v !== "string" || !TIME_RE.test(v)) fail(p, "must be YYYY-MM-DDTHH:MM:SSZ");
+  if (parseTime(v) === null) fail(p, "not a real time");
+};
+var bool = (v, p) => {
+  if (typeof v !== "boolean") fail(p, "must be true or false");
+};
+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 uint = (v, p) => {
+  if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0) {
+    fail(p, "must be a non-negative integer");
+  }
+};
+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 EXT = { ext: () => void 0, crit: () => void 0 };
+function checkExt(body) {
+  if (has(body, "ext") && !isPlainObject(body["ext"])) fail("ext", "must be an object");
+  if (has(body, "crit")) {
+    const crit = body["crit"];
+    if (!has(body, "ext")) fail("crit", "needs ext");
+    if (!Array.isArray(crit) || !crit.every((k) => typeof k === "string")) {
+      fail("crit", "must be a list of ext keys");
+    }
+    for (const key of crit) {
+      if (!has(body["ext"], key)) fail(`crit.${key}`, "not in ext");
+      fail(`crit.${key}`, "unknown critical extension");
+    }
+  }
+}
+function span(body, from, to) {
+  return parseTime(body[to]) - parseTime(body[from]);
+}
+var DAY = 24 * 60 * 60 * 1e3;
+var SCHEMAS = {
+  UamOwnerKeys(body) {
+    object(
+      {
+        type: constant("UamOwnerKeys"),
+        v: constant(1),
+        owner: keysOwner,
+        seq: uint,
+        keys: list(object({ id: passkey, rpId: domain, backupEligible: bool, label }), 1, 16)
+      },
+      {
+        prev: hash,
+        removed: list(object({ id: passkey, reason: oneOf("removed", "compromised") }), 1, 64),
+        recovery: bool,
+        ...EXT
+      }
+    )(body, "$");
+    const owner = body["owner"];
+    if (body["seq"] === 0) {
+      if (has(owner, "ownerId") || has(body, "prev")) fail("$", "entry 0 has no owner.ownerId and no prev");
+    } else if (!has(owner, "ownerId") || !has(body, "prev")) {
+      fail("$", "a later entry needs owner.ownerId and prev");
+    }
+  },
+  UamOwnerLink(body) {
+    object({
+      type: constant("UamOwnerLink"),
+      v: constant(1),
+      owner: ownerRef,
+      agent: address,
+      agentKey,
+      relay: domain,
+      via: oneOf("setup", "link"),
+      shared: bool,
+      effectiveAt: time,
+      validFrom: time,
+      nonce
+    }, { ...EXT })(body, "$");
+  },
+  UamOwnerUnlink(body) {
+    object({
+      type: constant("UamOwnerUnlink"),
+      v: constant(1),
+      owner: ownerRef,
+      agent: address,
+      agentKey,
+      reason: oneOf("owner", "admin", "relink", "authority", "lapsed"),
+      validFrom: time,
+      nonce
+    }, { ...EXT })(body, "$");
+  },
+  UamInvite(body) {
+    object(
+      {
+        type: constant("UamInvite"),
+        v: constant(1),
+        inviter: ownerRef,
+        offer: access,
+        ask: access,
+        secretHash: hash,
+        mode: oneOf("preapproved", "confirm"),
+        maxUses: constant(1),
+        validFrom: time,
+        redeemBy: time,
+        nonce
+      },
+      { emailHash: hash, ...EXT }
+    )(body, "$");
+    if (body["mode"] === "preapproved" && !has(body, "emailHash")) {
+      fail("$.emailHash", "a pre-approved invite names the invitee's email");
+    }
+    const d = span(body, "validFrom", "redeemBy");
+    if (!(d > 0 && d <= INVITE_MAX_DAYS * DAY)) {
+      fail("$.redeemBy", `must be after validFrom, within ${INVITE_MAX_DAYS} days`);
+    }
+  },
+  UamRedemption(body) {
+    object({
+      type: constant("UamRedemption"),
+      v: constant(1),
+      invite: hash,
+      secret,
+      invitee: ownerRef,
+      issuer: passkey,
+      createdAt: time,
+      nonce
+    }, { ...EXT })(body, "$");
+  },
+  UamContactGrant(body) {
+    object({
+      type: constant("UamContactGrant"),
+      v: constant(1),
+      issuer: passkey,
+      issuerOwner: ownerRefNoKeys,
+      credentialSubject: subject,
+      authorization_details: list(object({
+        type: constant("uam_contact"),
+        actions: list(oneOf("message"), 1, 1),
+        locations: list(location)
+      }), 1, 8),
+      via: oneOf("intro_email", "intro_code", "intro_qr", "request", "carried_over"),
+      enforcer: domain,
+      validFrom: time,
+      validUntil: time,
+      nonce
+    }, { ...EXT })(body, "$");
+    const d = span(body, "validFrom", "validUntil");
+    if (!(d > 0 && d <= GRANT_MAX_DAYS * DAY)) {
+      fail("$.validUntil", `must be after validFrom, within ${GRANT_MAX_DAYS} days`);
+    }
+  },
+  // Who may message an agent, as its owner approved it (P2e). Only a change
+  // that widens it is signed; narrowing needs no passkey.
+  UamAgentPolicy(body) {
+    object({
+      type: constant("UamAgentPolicy"),
+      v: constant(1),
+      owner: ownerRef,
+      agent: address,
+      agentKey,
+      policy: oneOf("open", "contacts"),
+      sameOwner: bool,
+      validFrom: time,
+      nonce
+    }, { ...EXT })(body, "$");
+  }
+};
+var SUBJECTS = {
+  owner: object({ kind: constant("owner"), owner: ownerRef }),
+  invitee: object({ kind: constant("invitee"), invite: hash }),
+  agent: object({ kind: constant("agent"), id: agentKey, address })
+};
+function subject(value, path) {
+  const kind = isPlainObject(value) ? value["kind"] : void 0;
+  if (typeof kind !== "string" || !has(SUBJECTS, kind)) {
+    fail(`${path}.kind`, `must be one of ${Object.keys(SUBJECTS).join(", ")}`);
+  }
+  SUBJECTS[kind](value, path);
+}
+function validate(body) {
+  if (!isPlainObject(body)) throw new SignedObjectError("a body must be a JSON object");
+  encode(body);
+  const type = body["type"];
+  if (typeof type !== "string" || !has(SCHEMAS, type)) {
+    throw new SignedObjectError(`unknown type: ${JSON.stringify(type)}`);
+  }
+  SCHEMAS[type](body);
+  checkExt(body);
+}
+
+// src/protocol/webauthn.ts
+var import_node_crypto4 = require("crypto");
+var import_p256 = require("@noble/curves/p256");
+var ES256 = -7;
+var UP = 1;
+var UV = 4;
+var BE = 8;
+var AT = 64;
+var ED = 128;
+var WebAuthnError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "WebAuthnError";
+  }
+};
+function credentialDid(credential) {
+  return encodeDidKey("p256", credential.publicKey);
+}
+var sha256 = (...parts) => {
+  const h = (0, import_node_crypto4.createHash)("sha256");
+  for (const part of parts) h.update(part);
+  return new Uint8Array(h.digest());
+};
+var equal = (a, b) => a.length === b.length && a.every((byte, i) => byte === b[i]);
+function cbor(data, start) {
+  let i = start;
+  if (i >= data.length) throw new WebAuthnError("CBOR: truncated");
+  const first = data[i];
+  const major = first >> 5;
+  const info = first & 31;
+  i += 1;
+  if (major === 7) {
+    if (info === 20) return [false, i];
+    if (info === 21) return [true, i];
+    throw new WebAuthnError("CBOR: unsupported simple value or float");
+  }
+  let n;
+  if (info < 24) {
+    n = info;
+  } else if (info >= 24 && info <= 27) {
+    const size = 1 << info - 24;
+    if (i + size > data.length) throw new WebAuthnError("CBOR: truncated");
+    let big = 0n;
+    for (let k = 0; k < size; k += 1) big = big << 8n | BigInt(data[i + k]);
+    if (big > BigInt(Number.MAX_SAFE_INTEGER)) throw new WebAuthnError("CBOR: number too large");
+    n = Number(big);
+    i += size;
+  } else {
+    throw new WebAuthnError("CBOR: indefinite lengths are not supported");
+  }
+  if (major === 0) return [n, i];
+  if (major === 1) return [-1 - n, i];
+  if (major === 2 || major === 3) {
+    if (i + n > data.length) throw new WebAuthnError("CBOR: truncated");
+    const raw = data.slice(i, i + n);
+    i += n;
+    if (major === 2) return [raw, i];
+    try {
+      return [new TextDecoder("utf-8", { fatal: true }).decode(raw), i];
+    } catch {
+      throw new WebAuthnError("CBOR: text is not UTF-8");
+    }
+  }
+  if (major === 4) {
+    const items = [];
+    for (let k = 0; k < n; k += 1) {
+      const [item, next] = cbor(data, i);
+      items.push(item);
+      i = next;
+    }
+    return [items, i];
+  }
+  if (major === 5) {
+    const out = /* @__PURE__ */ new Map();
+    for (let k = 0; k < n; k += 1) {
+      const [key, afterKey] = cbor(data, i);
+      if (typeof key !== "number" && typeof key !== "string") {
+        throw new WebAuthnError("CBOR: map keys must be integers or text");
+      }
+      if (out.has(key)) throw new WebAuthnError("CBOR: duplicate map key");
+      const [value, afterValue] = cbor(data, afterKey);
+      out.set(key, value);
+      i = afterValue;
+    }
+    return [out, i];
+  }
+  throw new WebAuthnError("CBOR: tags are not supported");
+}
+function cborWhole(data) {
+  const [value, end] = cbor(data, 0);
+  if (end !== data.length) throw new WebAuthnError("CBOR: trailing bytes");
+  return value;
+}
+function checkClientData(raw, kind, challenge, origin) {
+  let data;
+  try {
+    data = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
+  } catch {
+    throw new WebAuthnError("clientDataJSON is not JSON");
+  }
+  if (data === null || typeof data !== "object" || Array.isArray(data)) {
+    throw new WebAuthnError("clientDataJSON is not an object");
+  }
+  const d = data;
+  if (d["type"] !== kind) throw new WebAuthnError(`clientData.type must be ${kind}`);
+  if (d["challenge"] !== Buffer.from(challenge).toString("base64url")) {
+    throw new WebAuthnError("clientData.challenge doesn't match");
+  }
+  if (d["origin"] !== origin) throw new WebAuthnError("clientData.origin doesn't match");
+  if ("crossOrigin" in d && d["crossOrigin"] !== false) {
+    throw new WebAuthnError("cross-origin ceremonies are refused");
+  }
+  if ("topOrigin" in d) throw new WebAuthnError("ceremonies in a frame are refused");
+}
+function checkAuthData(data, rpId) {
+  if (data.length < 37) throw new WebAuthnError("authenticatorData too short");
+  if (!equal(data.slice(0, 32), sha256(new TextEncoder().encode(rpId)))) {
+    throw new WebAuthnError("rpIdHash doesn't match");
+  }
+  const flags = data[32];
+  if (!(flags & UP)) throw new WebAuthnError("user not present");
+  if (!(flags & UV)) throw new WebAuthnError("user not verified");
+  const count = new DataView(data.buffer, data.byteOffset + 33, 4).getUint32(0, false);
+  return { flags, count };
+}
+function point(bytes) {
+  try {
+    return import_p256.p256.ProjectivePoint.fromHex(bytes);
+  } catch {
+    throw new WebAuthnError("not a P-256 point");
+  }
+}
+function verifyRegistration(args) {
+  checkClientData(args.clientDataJSON, "webauthn.create", args.challenge, args.origin);
+  const att = cborWhole(args.attestationObject);
+  if (!(att instanceof Map) || att.size !== 3 || !att.has("fmt") || !att.has("attStmt") || !att.has("authData")) {
+    throw new WebAuthnError("attestationObject must have fmt, attStmt and authData");
+  }
+  const stmt = att.get("attStmt");
+  if (att.get("fmt") !== "none" || !(stmt instanceof Map) || stmt.size !== 0) {
+    throw new WebAuthnError("only attestation format 'none' is accepted");
+  }
+  const data = att.get("authData");
+  if (!(data instanceof Uint8Array)) throw new WebAuthnError("authData must be bytes");
+  const { flags, count } = checkAuthData(data, args.rpId);
+  if (!(flags & AT)) throw new WebAuthnError("no attested credential data");
+  if (data.length < 55) throw new WebAuthnError("attested credential data too short");
+  const idLen = data[53] << 8 | data[54];
+  const credentialId = data.slice(55, 55 + idLen);
+  if (credentialId.length !== idLen) throw new WebAuthnError("credential id truncated");
+  const [cose, end] = cbor(data, 55 + idLen);
+  if (!(flags & ED) && end !== data.length) {
+    throw new WebAuthnError("trailing bytes after the credential key");
+  }
+  if (!(cose instanceof Map) || cose.get(1) !== 2 || cose.get(3) !== ES256 || cose.get(-1) !== 1) {
+    throw new WebAuthnError("only ES256 (P-256) passkeys are accepted");
+  }
+  const x = cose.get(-2);
+  const y = cose.get(-3);
+  if (!(x instanceof Uint8Array) || !(y instanceof Uint8Array) || x.length !== 32 || y.length !== 32) {
+    throw new WebAuthnError("bad P-256 coordinates");
+  }
+  const key = point(new Uint8Array([4, ...x, ...y]));
+  return {
+    id: credentialId,
+    alg: ES256,
+    publicKey: key.toRawBytes(true),
+    backupEligible: Boolean(flags & BE),
+    signCount: count
+  };
+}
+function verifyAssertion(credential, args) {
+  if (credential.alg !== ES256) throw new WebAuthnError("only ES256 (P-256) passkeys are accepted");
+  checkClientData(args.clientDataJSON, "webauthn.get", args.challenge, args.origin);
+  const { flags, count } = checkAuthData(args.authenticatorData, args.rpId);
+  if (Boolean(flags & BE) !== credential.backupEligible) {
+    throw new WebAuthnError("backup eligibility changed since registration");
+  }
+  const key = point(credential.publicKey);
+  const digest = sha256(args.authenticatorData, sha256(args.clientDataJSON));
+  let ok = false;
+  try {
+    ok = import_p256.p256.verify(args.signature, digest, key.toRawBytes(false), {
+      format: "der",
+      lowS: false,
+      prehash: false
+    });
+  } catch {
+    ok = false;
+  }
+  if (!ok) throw new WebAuthnError("bad signature");
+  const checkCounter = args.checkCounter ?? true;
+  if (checkCounter && (count || credential.signCount) && count <= credential.signCount) {
+    throw new WebAuthnError("sign count didn't go up: the passkey may have been cloned");
+  }
+  return count;
+}
+function approvalChallenge(items, screen) {
+  if (items.length === 0) throw new WebAuthnError("an approval covers at least one object");
+  const body = {
+    set: items.map(([t, h]) => ({ t, h })),
+    screen: (0, import_node_crypto4.createHash)("sha256").update(screen, "utf8").digest("hex")
+  };
+  let data;
+  try {
+    data = canonical(body);
+  } catch (err) {
+    if (err instanceof SignedObjectError) throw new WebAuthnError(`bad approval set: ${err.message}`);
+    throw err;
+  }
+  return sha256(new TextEncoder().encode("UAM-APPROVAL-v1\n"), data);
+}
+
+// src/version.ts
+var SDK_VERSION = "0.4.0";
+
 // 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",
@@ -712,9 +1525,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 {
@@ -725,6 +1542,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) {
@@ -758,6 +1576,27 @@ var SDKConfig = class {
   }
 };
 
+// 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/key-manager.ts
 var import_node_fs = require("fs");
 var import_node_fs2 = require("fs");
@@ -828,17 +1667,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();
@@ -849,6 +1725,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") {
@@ -872,10 +1762,60 @@ var KeyManager = class {
   }
 };
 
+// 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";
+}
+function supports(features, name, version = 1) {
+  const prefix = `${name}:`;
+  for (const feature of features) {
+    if (feature === name && version <= 1) return true;
+    if (feature.startsWith(prefix)) {
+      const rest = feature.slice(prefix.length);
+      if (/^\d+$/.test(rest) && Number(rest) >= version) return true;
+    }
+  }
+  return false;
+}
+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;
@@ -955,36 +1895,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);
@@ -996,11 +1936,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;
@@ -1017,8 +1976,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.
@@ -1039,13 +1998,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.
@@ -1064,9 +2023,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.
@@ -1086,31 +2045,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;
   }
   /**
@@ -1118,8 +2077,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";
   }
   /**
@@ -1173,6 +2132,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;
@@ -1215,7 +2186,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;
@@ -1233,6 +2204,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,
@@ -1251,8 +2223,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"
@@ -1309,6 +2319,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";
@@ -1361,8 +2375,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()) {
@@ -1425,15 +2439,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(
@@ -1445,8 +2457,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);
@@ -1458,37 +2470,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);
   }
 };
 
@@ -1497,15 +2509,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() {
   }
@@ -1525,6 +2545,7 @@ var HTTPTransport = class extends TransportBase {
         `HTTP send failed: ${resp.status} ${resp.statusText}`
       );
     }
+    return readAnswer(resp);
   }
   async receive(limit = 50) {
     const url = new URL(
@@ -1556,8 +2577,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 = [];
@@ -1566,9 +2590,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() {
@@ -1589,7 +2624,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);
@@ -1601,12 +2643,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);
@@ -1616,11 +2688,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;
@@ -1641,6 +2749,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);
@@ -1657,33 +2768,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;
@@ -1700,6 +3057,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.
    */
@@ -1721,6 +3095,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'). */
@@ -1734,7 +3115,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() {
@@ -1771,10 +3152,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 {
@@ -1797,6 +3187,7 @@ var Agent = class {
    */
   async close() {
     this._contactBook.close();
+    await this._replayCache.close();
     if (this._transport) {
       await this._transport.disconnect();
     }
@@ -1804,7 +3195,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();
@@ -1817,7 +3213,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(
@@ -1835,20 +3232,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();
@@ -1856,7 +3262,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);
@@ -1876,42 +3290,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).
@@ -1937,7 +3352,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;
@@ -1958,7 +3373,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)
           }
         );
@@ -2011,7 +3426,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));
       }
@@ -2029,6 +3444,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.
@@ -2052,9 +3471,6 @@ var Agent = class {
         );
       }
     }
-    this._contactBook.addContact(toAddress, resolvedPkStr, {
-      trustState: "provisional"
-    });
     return deserializeVerifyKey(resolvedPkStr);
   }
   async _initiateHandshake(toAddress, recipientVk) {
@@ -2101,6 +3517,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);
     }
@@ -2135,6 +3554,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).
    */
@@ -2187,7 +3702,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);
@@ -2197,26 +3713,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();
@@ -2225,20 +3740,157 @@ 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/sdk/webhook-verify.ts
-var import_node_crypto3 = require("crypto");
+var import_node_crypto5 = require("crypto");
+function verifyWebhookSignature(payload, signatureHeader, secret2) {
+  if (!signatureHeader.startsWith("sha256=")) {
+    return false;
+  }
+  const expected = (0, import_node_crypto5.createHmac)("sha256", secret2).update(payload).digest("hex");
+  const received = signatureHeader.slice("sha256=".length);
+  const expectedBuf = Buffer.from(expected, "utf-8");
+  const receivedBuf = Buffer.from(received, "utf-8");
+  if (expectedBuf.length !== receivedBuf.length) {
+    return false;
+  }
+  return (0, import_node_crypto5.timingSafeEqual)(expectedBuf, receivedBuf);
+}
 
 // src/sdk/index.ts
 init_dns_verifier();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Agent,
-  protocol
+  ContactBook,
+  PENDING_NOTE,
+  SEND_STATUSES,
+  pendingNote,
+  protocol,
+  supports,
+  verifyWebhookSignature
 });
 //# sourceMappingURL=index.cjs.map