@youam/sdk 0.1.0 → 0.2.1

package/dist/index.js

@@ -0,0 +1,2946 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/sdk/dns-verifier.ts
+var dns_verifier_exports = {};
+__export(dns_verifier_exports, {
+  extractPublicKey: () => extractPublicKey,
+  generateTxtRecord: () => generateTxtRecord,
+  parseUamTxt: () => parseUamTxt,
+  queryUamTxt: () => queryUamTxt,
+  resolveKeyViaHttps: () => resolveKeyViaHttps
+});
+import { resolveTxt as dnsResolveTxt } from "dns/promises";
+function parseUamTxt(txtValue) {
+  const tags = {};
+  for (const part of txtValue.split(";")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx !== -1) {
+      const tag = trimmed.slice(0, eqIdx).trim().toLowerCase();
+      const value = trimmed.slice(eqIdx + 1).trim();
+      tags[tag] = value;
+    }
+  }
+  return tags;
+}
+function extractPublicKey(tags) {
+  const keyValue = tags["key"] ?? "";
+  if (keyValue.startsWith("ed25519:")) {
+    return keyValue.slice("ed25519:".length);
+  }
+  return null;
+}
+async function queryUamTxt(domain, timeout) {
+  const controller = new AbortController();
+  const timer = timeout != null ? setTimeout(() => controller.abort(), timeout) : void 0;
+  try {
+    const records = await dnsResolveTxt(`_uam.${domain}`);
+    const results = [];
+    for (const parts of records) {
+      const txtValue = parts.join("");
+      if (txtValue.trim().startsWith("v=uam1")) {
+        results.push(txtValue);
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  } finally {
+    if (timer != null) clearTimeout(timer);
+  }
+}
+async function resolveKeyViaHttps(agentName, domain, timeout) {
+  const url = `https://${domain}/.well-known/uam.json`;
+  try {
+    const resp = await fetch(url, {
+      signal: AbortSignal.timeout(timeout ?? 1e4)
+    });
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    if (data["v"] !== "uam1") return null;
+    const agents = data["agents"] ?? {};
+    const entry = agents[agentName];
+    if (!entry) return null;
+    let keyValue = entry["key"] ?? "";
+    if (keyValue.startsWith("ed25519:")) {
+      keyValue = keyValue.slice("ed25519:".length);
+    }
+    return keyValue || null;
+  } catch {
+    return null;
+  }
+}
+function generateTxtRecord(publicKey, relayUrl) {
+  return `v=uam1; key=ed25519:${publicKey}; relay=${relayUrl}`;
+}
+var init_dns_verifier = __esm({
+  "src/sdk/dns-verifier.ts"() {
+    "use strict";
+  }
+});
+
+// src/sdk/agent.ts
+import { join as join4 } from "path";
+
+// src/protocol/index.ts
+var protocol_exports = {};
+__export(protocol_exports, {
+  DecryptionError: () => DecryptionError,
+  EncryptionError: () => EncryptionError,
+  EnvelopeTooLargeError: () => EnvelopeTooLargeError,
+  InvalidAddressError: () => InvalidAddressError,
+  InvalidContactCardError: () => InvalidContactCardError,
+  InvalidEnvelopeError: () => InvalidEnvelopeError,
+  KeyPinningError: () => KeyPinningError,
+  MAX_ENVELOPE_AGE: () => MAX_ENVELOPE_AGE,
+  MAX_ENVELOPE_SIZE: () => MAX_ENVELOPE_SIZE,
+  MessageType: () => MessageType,
+  SignatureError: () => SignatureError,
+  SignatureVerificationError: () => SignatureVerificationError,
+  UAMError: () => UAMError,
+  UAM_VERSION: () => UAM_VERSION,
+  b64Decode: () => b64Decode,
+  b64Encode: () => b64Encode,
+  canonicalize: () => canonicalize,
+  contactCardFromDict: () => contactCardFromDict,
+  contactCardToDict: () => contactCardToDict,
+  createContactCard: () => createContactCard,
+  createEnvelope: () => createEnvelope,
+  decryptPayload: () => decryptPayload,
+  decryptPayloadAnonymous: () => decryptPayloadAnonymous,
+  deserializeSigningKey: () => deserializeSigningKey,
+  deserializeVerifyKey: () => deserializeVerifyKey,
+  encryptPayload: () => encryptPayload,
+  encryptPayloadAnonymous: () => encryptPayloadAnonymous,
+  fromWireDict: () => fromWireDict,
+  generateKeypair: () => generateKeypair,
+  generateNonce: () => generateNonce,
+  parseAddress: () => parseAddress,
+  publicKeyFingerprint: () => publicKeyFingerprint,
+  serializeSigningKey: () => serializeSigningKey,
+  serializeVerifyKey: () => serializeVerifyKey,
+  signMessage: () => signMessage,
+  sodiumReady: () => sodiumReady,
+  toWireDict: () => toWireDict,
+  utcTimestamp: () => utcTimestamp,
+  validateEnvelopeSize: () => validateEnvelopeSize,
+  verifyContactCard: () => verifyContactCard,
+  verifyEnvelope: () => verifyEnvelope,
+  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";
+  MessageType2["HANDSHAKE_ACCEPT"] = "handshake.accept";
+  MessageType2["HANDSHAKE_DENY"] = "handshake.deny";
+  MessageType2["RECEIPT_DELIVERED"] = "receipt.delivered";
+  MessageType2["RECEIPT_READ"] = "receipt.read";
+  MessageType2["RECEIPT_FAILED"] = "receipt.failed";
+  MessageType2["SESSION_REQUEST"] = "session.request";
+  MessageType2["SESSION_ACCEPT"] = "session.accept";
+  MessageType2["SESSION_DECLINE"] = "session.decline";
+  MessageType2["SESSION_END"] = "session.end";
+  return MessageType2;
+})(MessageType || {});
+function b64Encode(data) {
+  return Buffer.from(data).toString("base64url");
+}
+function b64Decode(s) {
+  return new Uint8Array(Buffer.from(s, "base64url"));
+}
+function utcTimestamp() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/protocol/errors.ts
+var UAMError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UAMError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidAddressError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidAddressError";
+  }
+};
+var InvalidEnvelopeError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidEnvelopeError";
+  }
+};
+var EnvelopeTooLargeError = class extends InvalidEnvelopeError {
+  constructor(message) {
+    super(message);
+    this.name = "EnvelopeTooLargeError";
+  }
+};
+var SignatureError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "SignatureError";
+  }
+};
+var SignatureVerificationError = class extends SignatureError {
+  constructor(message) {
+    super(message);
+    this.name = "SignatureVerificationError";
+  }
+};
+var EncryptionError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "EncryptionError";
+  }
+};
+var DecryptionError = class extends EncryptionError {
+  constructor(message) {
+    super(message);
+    this.name = "DecryptionError";
+  }
+};
+var InvalidContactCardError = class extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidContactCardError";
+  }
+};
+var KeyPinningError = class _KeyPinningError extends UAMError {
+  constructor(message) {
+    super(message);
+    this.name = "KeyPinningError";
+    Object.setPrototypeOf(this, _KeyPinningError.prototype);
+  }
+};
+
+// 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])?)$/;
+var MAX_AGENT_LEN = 64;
+var MAX_ADDRESS_LEN = 128;
+function parseAddress(raw) {
+  const normalized = raw.trim().toLowerCase();
+  if (normalized.length > MAX_ADDRESS_LEN) {
+    throw new InvalidAddressError(
+      `Address exceeds ${MAX_ADDRESS_LEN} characters: ${JSON.stringify(raw)}`
+    );
+  }
+  const m = ADDRESS_RE.exec(normalized);
+  if (!m || !m.groups) {
+    throw new InvalidAddressError(
+      `Invalid UAM address: ${JSON.stringify(raw)}`
+    );
+  }
+  const agent = m.groups.agent;
+  if (agent.length > MAX_AGENT_LEN) {
+    throw new InvalidAddressError(
+      `Agent name exceeds ${MAX_AGENT_LEN} characters: ${JSON.stringify(raw)}`
+    );
+  }
+  return {
+    agent,
+    domain: m.groups.domain,
+    get full() {
+      return `${this.agent}::${this.domain}`;
+    }
+  };
+}
+
+// src/protocol/crypto.ts
+import sodium from "libsodium-wrappers";
+import { createHash } from "crypto";
+var sodiumReady = sodium.ready;
+function generateKeypair() {
+  const seed = sodium.randombytes_buf(32);
+  const kp = sodium.crypto_sign_seed_keypair(seed);
+  return {
+    signingKey: kp.privateKey,
+    verifyKey: kp.publicKey,
+    seed
+  };
+}
+function serializeSigningKey(seed) {
+  return b64Encode(seed);
+}
+function deserializeSigningKey(s) {
+  const seed = b64Decode(s);
+  const kp = sodium.crypto_sign_seed_keypair(seed);
+  return {
+    signingKey: kp.privateKey,
+    verifyKey: kp.publicKey,
+    seed
+  };
+}
+function serializeVerifyKey(key) {
+  return b64Encode(key);
+}
+function deserializeVerifyKey(s) {
+  return b64Decode(s);
+}
+function publicKeyFingerprint(verifyKey) {
+  return createHash("sha256").update(Buffer.from(verifyKey)).digest("hex");
+}
+function sortedStringify(value) {
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((v) => sortedStringify(v));
+    return "[" + items.join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const pairs = keys.map((k) => JSON.stringify(k) + ":" + sortedStringify(obj[k]));
+    return "{" + pairs.join(",") + "}";
+  }
+  return String(value);
+}
+function canonicalize(data) {
+  const filtered = {};
+  for (const [k, v] of Object.entries(data)) {
+    if (k !== "signature" && v !== null && v !== void 0) {
+      filtered[k] = v;
+    }
+  }
+  const json = sortedStringify(filtered);
+  return new TextEncoder().encode(json);
+}
+function signMessage(data, signingKey) {
+  const signature = sodium.crypto_sign_detached(data, signingKey);
+  return b64Encode(signature);
+}
+function verifySignature(data, signatureB64, verifyKey) {
+  try {
+    const sigBytes = b64Decode(signatureB64);
+    const valid = sodium.crypto_sign_verify_detached(sigBytes, data, verifyKey);
+    if (!valid) {
+      throw new SignatureVerificationError("Signature verification failed");
+    }
+  } catch (err) {
+    if (err instanceof SignatureVerificationError) {
+      throw err;
+    }
+    throw new SignatureVerificationError(
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+function generateNonce() {
+  return b64Encode(sodium.randombytes_buf(24));
+}
+function encryptPayload(plaintext, senderSigningKey, recipientVerifyKey) {
+  try {
+    const senderCurve = sodium.crypto_sign_ed25519_sk_to_curve25519(senderSigningKey);
+    const recipientCurve = sodium.crypto_sign_ed25519_pk_to_curve25519(recipientVerifyKey);
+    const nonce = sodium.randombytes_buf(sodium.crypto_box_NONCEBYTES);
+    const encrypted = sodium.crypto_box_easy(plaintext, nonce, recipientCurve, senderCurve);
+    const combined = new Uint8Array(nonce.length + encrypted.length);
+    combined.set(nonce, 0);
+    combined.set(encrypted, nonce.length);
+    return b64Encode(combined);
+  } catch (err) {
+    if (err instanceof EncryptionError) throw err;
+    throw new EncryptionError(err instanceof Error ? err.message : String(err));
+  }
+}
+function decryptPayload(ciphertextB64, recipientSigningKey, senderVerifyKey) {
+  try {
+    const combined = b64Decode(ciphertextB64);
+    const nonce = combined.slice(0, sodium.crypto_box_NONCEBYTES);
+    const ciphertext = combined.slice(sodium.crypto_box_NONCEBYTES);
+    const recipientCurve = sodium.crypto_sign_ed25519_sk_to_curve25519(recipientSigningKey);
+    const senderCurve = sodium.crypto_sign_ed25519_pk_to_curve25519(senderVerifyKey);
+    return sodium.crypto_box_open_easy(ciphertext, nonce, senderCurve, recipientCurve);
+  } catch (err) {
+    if (err instanceof DecryptionError) throw err;
+    throw new DecryptionError(err instanceof Error ? err.message : String(err));
+  }
+}
+function encryptPayloadAnonymous(plaintext, recipientVerifyKey) {
+  const recipientCurve = sodium.crypto_sign_ed25519_pk_to_curve25519(recipientVerifyKey);
+  const ciphertext = sodium.crypto_box_seal(plaintext, recipientCurve);
+  return b64Encode(ciphertext);
+}
+function decryptPayloadAnonymous(ciphertextB64, recipientSigningKey) {
+  try {
+    const ciphertext = b64Decode(ciphertextB64);
+    const recipientCurveSk = sodium.crypto_sign_ed25519_sk_to_curve25519(recipientSigningKey);
+    const recipientVerifyKey = recipientSigningKey.slice(32);
+    const recipientCurvePk = sodium.crypto_sign_ed25519_pk_to_curve25519(recipientVerifyKey);
+    return sodium.crypto_box_seal_open(ciphertext, recipientCurvePk, recipientCurveSk);
+  } catch (err) {
+    if (err instanceof DecryptionError) throw err;
+    throw new DecryptionError(err instanceof Error ? err.message : String(err));
+  }
+}
+
+// src/protocol/envelope.ts
+import { randomUUID } from "crypto";
+var REQUIRED_WIRE_FIELDS = /* @__PURE__ */ new Set([
+  "uam_version",
+  "message_id",
+  "from",
+  "to",
+  "timestamp",
+  "type",
+  "nonce",
+  "payload",
+  "signature"
+]);
+function buildSignableDict(envelope) {
+  const d = {
+    uam_version: envelope.uamVersion,
+    message_id: envelope.messageId,
+    from: envelope.fromAddress,
+    to: envelope.toAddress,
+    timestamp: envelope.timestamp,
+    type: envelope.type,
+    nonce: envelope.nonce,
+    payload: envelope.payload
+  };
+  if (envelope.threadId !== void 0) d["thread_id"] = envelope.threadId;
+  if (envelope.replyTo !== void 0) d["reply_to"] = envelope.replyTo;
+  if (envelope.expires !== void 0) d["expires"] = envelope.expires;
+  if (envelope.mediaType !== void 0) d["media_type"] = envelope.mediaType;
+  if (envelope.metadata !== void 0) d["metadata"] = envelope.metadata;
+  return d;
+}
+function toWireDict(envelope) {
+  const d = buildSignableDict(envelope);
+  d["signature"] = envelope.signature;
+  if (envelope.attachments !== void 0) {
+    d["attachments"] = envelope.attachments;
+  }
+  return d;
+}
+function fromWireDict(d) {
+  const keys = new Set(Object.keys(d));
+  const missing = [];
+  for (const field of REQUIRED_WIRE_FIELDS) {
+    if (!keys.has(field)) missing.push(field);
+  }
+  if (missing.length > 0) {
+    missing.sort();
+    throw new InvalidEnvelopeError(
+      `Missing required fields: ${JSON.stringify(missing)}`
+    );
+  }
+  return Object.freeze({
+    uamVersion: d["uam_version"],
+    messageId: d["message_id"],
+    fromAddress: d["from"],
+    toAddress: d["to"],
+    timestamp: d["timestamp"],
+    type: d["type"],
+    nonce: d["nonce"],
+    payload: d["payload"],
+    signature: d["signature"],
+    threadId: d["thread_id"],
+    replyTo: d["reply_to"],
+    expires: d["expires"],
+    mediaType: d["media_type"],
+    metadata: d["metadata"],
+    attachments: d["attachments"]
+  });
+}
+function validateEnvelopeSize(envelope) {
+  const wire = toWireDict(envelope);
+  const json = JSON.stringify(wire);
+  const size = new TextEncoder().encode(json).length;
+  if (size > MAX_ENVELOPE_SIZE) {
+    throw new EnvelopeTooLargeError(
+      `Envelope size ${size} bytes exceeds maximum ${MAX_ENVELOPE_SIZE} bytes`
+    );
+  }
+}
+async function createEnvelope(fromAddress, toAddress, messageType, payloadPlaintext, signingKey, recipientVerifyKey, options) {
+  const typeValue = typeof messageType === "string" ? messageType : messageType;
+  parseAddress(fromAddress);
+  parseAddress(toAddress);
+  const messageId = randomUUID();
+  const nonce = generateNonce();
+  const timestamp = utcTimestamp();
+  let encryptedPayload;
+  if (typeValue === "handshake.request" /* HANDSHAKE_REQUEST */) {
+    encryptedPayload = encryptPayloadAnonymous(payloadPlaintext, recipientVerifyKey);
+  } else {
+    encryptedPayload = encryptPayload(
+      payloadPlaintext,
+      signingKey,
+      recipientVerifyKey
+    );
+  }
+  const tempEnvelope = {
+    uamVersion: UAM_VERSION,
+    messageId,
+    fromAddress,
+    toAddress,
+    timestamp,
+    type: typeValue,
+    nonce,
+    payload: encryptedPayload,
+    signature: "",
+    threadId: options?.threadId,
+    replyTo: options?.replyTo,
+    expires: options?.expires,
+    mediaType: options?.mediaType,
+    metadata: options?.metadata,
+    attachments: options?.attachments
+  };
+  const signable = buildSignableDict(tempEnvelope);
+  const signature = signMessage(canonicalize(signable), signingKey);
+  const finalEnvelope = Object.freeze({
+    uamVersion: UAM_VERSION,
+    messageId,
+    fromAddress,
+    toAddress,
+    timestamp,
+    type: typeValue,
+    nonce,
+    payload: encryptedPayload,
+    signature,
+    threadId: options?.threadId,
+    replyTo: options?.replyTo,
+    expires: options?.expires,
+    mediaType: options?.mediaType,
+    metadata: options?.metadata,
+    attachments: options?.attachments
+  });
+  validateEnvelopeSize(finalEnvelope);
+  return finalEnvelope;
+}
+function verifyEnvelope(envelope, senderVerifyKey) {
+  const signable = buildSignableDict(envelope);
+  verifySignature(canonicalize(signable), envelope.signature, senderVerifyKey);
+}
+
+// src/protocol/contact.ts
+function buildSignableDict2(card) {
+  const d = {
+    version: card.version,
+    address: card.address,
+    display_name: card.displayName,
+    relay: card.relay,
+    public_key: card.publicKey
+  };
+  if (card.description !== void 0) d["description"] = card.description;
+  if (card.system !== void 0) d["system"] = card.system;
+  if (card.connectionEndpoint !== void 0) {
+    d["connection_endpoint"] = card.connectionEndpoint;
+  }
+  if (card.verifiedDomain !== void 0) {
+    d["verified_domain"] = card.verifiedDomain;
+  }
+  return d;
+}
+function contactCardToDict(card) {
+  const d = buildSignableDict2(card);
+  d["signature"] = card.signature;
+  if (card.payloadFormats !== void 0) {
+    d["payload_formats"] = card.payloadFormats;
+  }
+  if (card.fingerprint !== void 0) {
+    d["fingerprint"] = card.fingerprint;
+  }
+  if (card.relays !== void 0) {
+    d["relays"] = card.relays;
+  }
+  return d;
+}
+function contactCardFromDict(d, options) {
+  const verify = options?.verify ?? true;
+  const required = /* @__PURE__ */ new Set([
+    "version",
+    "address",
+    "display_name",
+    "relay",
+    "public_key",
+    "signature"
+  ]);
+  const keys = new Set(Object.keys(d));
+  const missing = [];
+  for (const field of required) {
+    if (!keys.has(field)) missing.push(field);
+  }
+  if (missing.length > 0) {
+    missing.sort();
+    throw new InvalidContactCardError(
+      `Missing required fields: ${JSON.stringify(missing)}`
+    );
+  }
+  const card = Object.freeze({
+    version: d["version"],
+    address: d["address"],
+    displayName: d["display_name"],
+    description: d["description"],
+    system: d["system"],
+    connectionEndpoint: d["connection_endpoint"],
+    relay: d["relay"],
+    publicKey: d["public_key"],
+    signature: d["signature"],
+    verifiedDomain: d["verified_domain"],
+    payloadFormats: d["payload_formats"],
+    fingerprint: d["fingerprint"],
+    relays: d["relays"]
+  });
+  if (verify) {
+    verifyContactCard(card);
+  }
+  return card;
+}
+async function createContactCard(address, displayName, relay, signingKey, options) {
+  parseAddress(address);
+  const verifyKey = signingKey.slice(32);
+  const pubKeyB64 = serializeVerifyKey(verifyKey);
+  const fp = publicKeyFingerprint(verifyKey);
+  const payloadFormats = options?.payloadFormats ?? [
+    "text/plain",
+    "text/markdown"
+  ];
+  const tempCard = {
+    version: UAM_VERSION,
+    address,
+    displayName,
+    description: options?.description,
+    system: options?.system,
+    connectionEndpoint: options?.connectionEndpoint,
+    relay,
+    publicKey: pubKeyB64,
+    signature: "",
+    verifiedDomain: options?.verifiedDomain,
+    payloadFormats,
+    fingerprint: fp,
+    relays: options?.relays
+  };
+  const signable = buildSignableDict2(tempCard);
+  const signature = signMessage(canonicalize(signable), signingKey);
+  return Object.freeze({
+    version: UAM_VERSION,
+    address,
+    displayName,
+    description: options?.description,
+    system: options?.system,
+    connectionEndpoint: options?.connectionEndpoint,
+    relay,
+    publicKey: pubKeyB64,
+    signature,
+    verifiedDomain: options?.verifiedDomain,
+    payloadFormats,
+    fingerprint: fp,
+    relays: options?.relays
+  });
+}
+function verifyContactCard(card) {
+  try {
+    parseAddress(card.address);
+  } catch (err) {
+    throw new InvalidContactCardError(
+      `Invalid address in contact card: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const vk = deserializeVerifyKey(card.publicKey);
+  const signable = buildSignableDict2(card);
+  verifySignature(canonicalize(signable), card.signature, vk);
+}
+
+// src/version.ts
+var SDK_VERSION = "0.2.1";
+
+// src/sdk/config.ts
+import { homedir } from "os";
+import { join } from "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",
+  "allowlist-only",
+  "require_verify"
+]);
+var SDKConfig = class {
+  name;
+  relayUrl;
+  relayWsUrl;
+  keyDir;
+  dataDir;
+  displayName;
+  transportType;
+  trustPolicy;
+  relayDomain;
+  /** The domain the caller chose, if any; null when only derived. */
+  explicitRelayDomain;
+  constructor(options) {
+    this.name = options.name;
+    this.relayUrl = trimRelayUrl(
+      options.relayUrl ?? process.env["UAM_RELAY_URL"] ?? DEFAULT_RELAY_URL
+    );
+    if (options.relayWsUrl) {
+      this.relayWsUrl = options.relayWsUrl;
+    } else {
+      let wsUrl = this.relayUrl.replace("https://", "wss://").replace("http://", "ws://");
+      if (!wsUrl.endsWith("/ws")) {
+        wsUrl = wsUrl.replace(/\/+$/, "") + "/ws";
+      }
+      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) {
+      this.relayDomain = options.relayDomain;
+    } else {
+      try {
+        const parsed = new URL(this.relayUrl);
+        this.relayDomain = parsed.hostname || "localhost";
+      } catch {
+        const afterScheme = this.relayUrl.split("://").pop() || "";
+        this.relayDomain = afterScheme.split("/")[0] || "localhost";
+      }
+    }
+    const uamHome = process.env["UAM_HOME"];
+    const defaultHome = uamHome || join(homedir(), ".uam");
+    this.keyDir = options.keyDir ?? join(defaultHome, "keys");
+    this.dataDir = options.dataDir ?? defaultHome;
+    this.displayName = options.displayName ?? this.name;
+    this.transportType = options.transportType ?? "websocket";
+    let policy = options.trustPolicy ?? "auto-accept";
+    const envPolicy = process.env["UAM_TRUST_POLICY"];
+    if (envPolicy) {
+      policy = envPolicy;
+    }
+    if (!VALID_POLICIES.has(policy)) {
+      throw new Error(
+        `Invalid trust_policy '${policy}'. Must be one of: ${JSON.stringify([...VALID_POLICIES].sort())}`
+      );
+    }
+    this.trustPolicy = policy;
+  }
+};
+
+// 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
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync
+} from "fs";
+import { existsSync } from "fs";
+import { join as join2 } from "path";
+import { homedir as homedir2 } from "os";
+import { platform } from "os";
+var DEFAULT_KEY_DIR = join2(homedir2(), ".uam", "keys");
+var KeyManager = class {
+  _keyDir;
+  _keypair = null;
+  constructor(keyDir) {
+    this._keyDir = keyDir ?? DEFAULT_KEY_DIR;
+  }
+  /** The 64-byte Ed25519 signing key. Throws if not loaded. */
+  get signingKey() {
+    if (this._keypair === null) {
+      throw new Error("No keypair loaded. Call loadOrGenerate() first.");
+    }
+    return this._keypair.signingKey;
+  }
+  /** The 32-byte Ed25519 verify (public) key. Throws if not loaded. */
+  get verifyKey() {
+    if (this._keypair === null) {
+      throw new Error("No keypair loaded. Call loadOrGenerate() first.");
+    }
+    return this._keypair.verifyKey;
+  }
+  /** The 32-byte seed. Throws if not loaded. */
+  get seed() {
+    if (this._keypair === null) {
+      throw new Error("No keypair loaded. Call loadOrGenerate() first.");
+    }
+    return this._keypair.seed;
+  }
+  /**
+   * Load existing keypair or generate a new one.
+   *
+   * Checks UAM_SIGNING_KEY env var first (base64-encoded Ed25519 seed).
+   * Falls back to file-based storage at {keyDir}/{name}.key.
+   * Generates a new keypair if neither source exists.
+   */
+  loadOrGenerate(name) {
+    const envKey = process.env["UAM_SIGNING_KEY"];
+    if (envKey) {
+      this._keypair = deserializeSigningKey(envKey.trim());
+      return;
+    }
+    mkdirSync(this._keyDir, { recursive: true });
+    const keyPath = join2(this._keyDir, `${name}.key`);
+    const pubPath = join2(this._keyDir, `${name}.pub`);
+    if (existsSync(keyPath)) {
+      this._checkPermissions(keyPath);
+      const seedB64 = readFileSync(keyPath, "utf-8").trim();
+      this._keypair = deserializeSigningKey(seedB64);
+    } else {
+      this._keypair = generateKeypair();
+      writeFileSync(keyPath, serializeSigningKey(this._keypair.seed));
+      writeFileSync(pubPath, serializeVerifyKey(this._keypair.verifyKey));
+      this._setPermissions(keyPath);
+    }
+  }
+  /**
+   * Store the relay token alongside the keypair.
+   */
+  saveToken(name, token) {
+    mkdirSync(this._keyDir, { recursive: true });
+    const tokenPath = join2(this._keyDir, `${name}.token`);
+    writeFileSync(tokenPath, token);
+    this._setPermissions(tokenPath);
+  }
+  /**
+   * Store the address `relayUrl` gave this agent.
+   */
+  saveAddress(name, address, relayUrl) {
+    mkdirSync(this._keyDir, { recursive: true });
+    writeFileSync(
+      join2(this._keyDir, `${name}.address`),
+      JSON.stringify({ address, relay_url: relayUrl })
+    );
+  }
+  /**
+   * Load the address saved for `relayUrl`.
+   *
+   * Returns null if there is none: the file is missing, unreadable or
+   * malformed, or it belongs to another relay.
+   */
+  loadAddress(name, relayUrl) {
+    try {
+      const path = join2(this._keyDir, `${name}.address`);
+      const saved = JSON.parse(readFileSync(path, "utf-8"));
+      const address = saved?.address;
+      const savedRelay = saved?.relay_url;
+      if (typeof address !== "string" || typeof savedRelay !== "string") {
+        return null;
+      }
+      if (trimRelayUrl(savedRelay) !== trimRelayUrl(relayUrl)) return null;
+      parseAddress(address);
+      return address;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Load a previously saved token, or return null.
+   *
+   * Checks UAM_TOKEN env var first, then file-based storage,
+   * then legacy .api_key files for backward compatibility. 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, relayUrl) {
+    const envToken = process.env["UAM_TOKEN"];
+    if (envToken) {
+      return envToken.trim();
+    }
+    if (relayUrl !== void 0 && this._savedForAnotherRelay(name, relayUrl)) {
+      return null;
+    }
+    const tokenPath = join2(this._keyDir, `${name}.token`);
+    if (existsSync(tokenPath)) {
+      return readFileSync(tokenPath, "utf-8").trim();
+    }
+    const legacyPath = join2(this._keyDir, `${name}.api_key`);
+    if (existsSync(legacyPath)) {
+      return readFileSync(legacyPath, "utf-8").trim();
+    }
+    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 = join2(this._keyDir, `${name}.address`);
+      const saved = JSON.parse(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 (platform() !== "win32") {
+      chmodSync(path, 384);
+    }
+  }
+  /** Warn if key file permissions are too permissive. */
+  _checkPermissions(path) {
+    if (platform() === "win32") {
+      return;
+    }
+    try {
+      const mode = statSync(path).mode & 511;
+      if (mode !== 384) {
+        console.warn(
+          `Key file ${path} has permissions ${mode.toString(8)} (expected 600). Run: chmod 600 ${path}`
+        );
+      }
+    } catch {
+    }
+  }
+};
+
+// src/sdk/contact-book.ts
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join3, dirname } from "path";
+import Database from "better-sqlite3";
+
+// 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;
+  _knownAddresses = /* @__PURE__ */ new Set();
+  _blockedExact = /* @__PURE__ */ new Set();
+  _blockedDomains = /* @__PURE__ */ new Set();
+  constructor(dataDir) {
+    this._dbPath = join3(dataDir, "contacts", "contacts.db");
+  }
+  /**
+   * Open the database, create tables, run migrations, load caches.
+   */
+  open() {
+    mkdirSync2(dirname(this._dbPath), { recursive: true });
+    this._db = new Database(this._dbPath);
+    this._db.pragma("journal_mode = WAL");
+    this._db.exec(`
+      CREATE TABLE IF NOT EXISTS contacts (
+        address      TEXT PRIMARY KEY,
+        public_key   TEXT NOT NULL,
+        display_name TEXT,
+        trust_state  TEXT NOT NULL DEFAULT 'unknown',
+        trust_source TEXT DEFAULT 'legacy-unknown',
+        relay        TEXT,
+        relays_json  TEXT,
+        pinned_at    TEXT,
+        first_seen   TEXT NOT NULL DEFAULT (datetime('now')),
+        last_seen    TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS pending_handshakes (
+        address      TEXT PRIMARY KEY,
+        contact_card TEXT NOT NULL,
+        received_at  TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS blocked_patterns (
+        pattern     TEXT PRIMARY KEY,
+        blocked_at  TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+    `);
+    this._migrate();
+    const rows = this._db.prepare("SELECT address FROM contacts").all();
+    this._knownAddresses = new Set(rows.map((r) => r.address));
+    this._blockedExact.clear();
+    this._blockedDomains.clear();
+    const blocked = this._db.prepare("SELECT pattern FROM blocked_patterns").all();
+    for (const row of blocked) {
+      this._cacheBlockPattern(row.pattern);
+    }
+  }
+  /**
+   * Run schema migrations using PRAGMA user_version.
+   */
+  _migrate() {
+    if (!this._db) return;
+    const versionRow = this._db.prepare("PRAGMA user_version").get();
+    const version = versionRow.user_version;
+    if (version < 2) {
+      this._db.exec("PRAGMA user_version = 3");
+    } else if (version < 3) {
+      this._db.exec(
+        "ALTER TABLE contacts ADD COLUMN pinned_at TEXT"
+      );
+      this._db.exec("PRAGMA user_version = 3");
+    }
+  }
+  /**
+   * Close the database connection.
+   */
+  close() {
+    if (this._db !== null) {
+      this._db.close();
+      this._db = null;
+    }
+  }
+  /**
+   * Check if an address is in the contact book (in-memory, no I/O).
+   */
+  isKnown(address) {
+    return this._knownAddresses.has(address);
+  }
+  /**
+   * Check if an address matches any blocked pattern (O(1) set lookup).
+   */
+  isBlocked(address) {
+    if (this._blockedExact.has(address)) {
+      return true;
+    }
+    if (address.includes("::")) {
+      const domain = address.split("::")[1];
+      return this._blockedDomains.has(domain);
+    }
+    return false;
+  }
+  /**
+   * Look up the public key for a known contact.
+   */
+  getPublicKey(address) {
+    if (this._db === null) return null;
+    const row = this._db.prepare("SELECT public_key FROM contacts WHERE address = ?").get(address);
+    return row?.public_key ?? null;
+  }
+  /**
+   * Return the relay URLs for a known contact (CARD-04).
+   */
+  getRelayUrls(address) {
+    if (this._db === null) return null;
+    const row = this._db.prepare("SELECT relay, relays_json FROM contacts WHERE address = ?").get(address);
+    if (!row) return null;
+    if (row.relays_json !== null) {
+      return JSON.parse(row.relays_json);
+    }
+    if (row.relay !== null) {
+      return [row.relay];
+    }
+    return null;
+  }
+  /**
+   * Add or update a contact (upsert).
+   *
+   * Refuses to replace the key of a contact whose trust_state is "pinned"
+   * or "verified" with a different key, unless `force: true` is passed (for
+   * a deliberate key rotation, which is logged). Matches the Python SDK's
+   * ContactBook.add_contact.
+   *
+   * @throws {KeyPinningError} If a pinned/verified contact's key would be
+   *   replaced by a different key without `force`.
+   */
+  addContact(address, publicKey, options) {
+    if (this._db === null) {
+      throw new Error("ContactBook not open. Call open() first.");
+    }
+    const existing = this._db.prepare("SELECT public_key, trust_state FROM contacts WHERE address = ?").get(address);
+    if (existing !== void 0 && (existing.trust_state === "pinned" || existing.trust_state === "verified") && existing.public_key !== publicKey) {
+      if (!options?.force) {
+        throw new KeyPinningError(
+          `Refusing to overwrite ${existing.trust_state} contact ${JSON.stringify(address)}: stored public key does not match the new key. Pass force: true to rotate.`
+        );
+      }
+      log.warn(
+        `Force-replacing the key of ${existing.trust_state} contact ${address} (key rotation)`
+      );
+    }
+    const displayName = options?.displayName ?? null;
+    const trustState = options?.trustState ?? "trusted";
+    const trustSource = options?.trustSource ?? null;
+    const relay = options?.relay ?? null;
+    const relaysJson = options?.relays !== void 0 && options?.relays !== null ? JSON.stringify(options.relays) : null;
+    this._db.prepare(
+      `INSERT INTO contacts (address, public_key, display_name, trust_state, trust_source, relay, relays_json)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(address) DO UPDATE SET
+           public_key = excluded.public_key,
+           display_name = excluded.display_name,
+           trust_state = excluded.trust_state,
+           trust_source = COALESCE(excluded.trust_source, contacts.trust_source),
+           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);
+  }
+  /**
+   * Return all contacts sorted by last_seen DESC.
+   */
+  listContacts() {
+    if (this._db === null) return [];
+    const rows = this._db.prepare(
+      "SELECT address, display_name, trust_state, first_seen, last_seen FROM contacts ORDER BY last_seen DESC"
+    ).all();
+    return rows.map((r) => ({
+      address: r.address,
+      displayName: r.display_name,
+      trustState: r.trust_state,
+      firstSeen: r.first_seen,
+      lastSeen: r.last_seen
+    }));
+  }
+  /**
+   * Store a pending handshake request.
+   */
+  addPending(address, 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);
+  }
+  /**
+   * Retrieve all pending handshake requests.
+   */
+  getPending() {
+    if (this._db === null) return [];
+    const rows = this._db.prepare(
+      "SELECT address, contact_card, received_at FROM pending_handshakes"
+    ).all();
+    return rows.map((r) => ({
+      address: r.address,
+      contactCard: r.contact_card,
+      receivedAt: r.received_at
+    }));
+  }
+  /**
+   * Remove a pending handshake request.
+   */
+  removePending(address) {
+    if (this._db === null) return;
+    this._db.prepare("DELETE FROM pending_handshakes WHERE address = ?").run(address);
+  }
+  /**
+   * Return pending handshakes older than N days.
+   */
+  getExpiredPending(days = 7) {
+    if (this._db === null) return [];
+    const rows = this._db.prepare(
+      `SELECT address, contact_card, received_at FROM pending_handshakes
+         WHERE datetime(received_at, '+' || ? || ' days') < datetime('now')`
+    ).all(String(days));
+    return rows.map((r) => ({
+      address: r.address,
+      contactCard: r.contact_card,
+      receivedAt: r.received_at
+    }));
+  }
+  /**
+   * Return the trust_state for an address, or null if unknown.
+   */
+  getTrustState(address) {
+    if (this._db === null) return null;
+    const row = this._db.prepare("SELECT trust_state FROM contacts WHERE address = ?").get(address);
+    return row?.trust_state ?? null;
+  }
+  /**
+   * Set the pinned_at timestamp and trust_state='pinned' for a contact (TOFU).
+   */
+  setPinnedAt(address) {
+    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);
+  }
+  /**
+   * Remove a contact by address. Returns true if a contact was deleted.
+   */
+  removeContact(address) {
+    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);
+    return result.changes > 0;
+  }
+  /**
+   * Return true if the address has trust_state 'trusted', 'verified', or 'pinned'.
+   *
+   * Convenience helper for inbound message filtering (CARD-05, TOFU-02).
+   */
+  isTrustedOrVerified(address) {
+    const state = this.getTrustState(address);
+    return state === "trusted" || state === "verified" || state === "pinned";
+  }
+  /**
+   * Block an address or domain pattern (e.g., '*::evil.com').
+   */
+  addBlock(pattern) {
+    if (this._db === null) {
+      throw new Error("ContactBook not open. Call open() first.");
+    }
+    this._db.prepare("INSERT OR IGNORE INTO blocked_patterns (pattern) VALUES (?)").run(pattern);
+    this._cacheBlockPattern(pattern);
+  }
+  /**
+   * Remove a block pattern.
+   */
+  removeBlock(pattern) {
+    if (this._db === null) {
+      throw new Error("ContactBook not open. Call open() first.");
+    }
+    this._db.prepare("DELETE FROM blocked_patterns WHERE pattern = ?").run(pattern);
+    this._uncacheBlockPattern(pattern);
+  }
+  /**
+   * Return all blocked patterns with their timestamps.
+   */
+  listBlocked() {
+    if (this._db === null) return [];
+    const rows = this._db.prepare(
+      "SELECT pattern, blocked_at FROM blocked_patterns ORDER BY blocked_at DESC"
+    ).all();
+    return rows.map((r) => ({
+      pattern: r.pattern,
+      blockedAt: r.blocked_at
+    }));
+  }
+  // -- Internal block caching ---------------------------------------------------
+  _cacheBlockPattern(pattern) {
+    if (pattern.startsWith("*::")) {
+      this._blockedDomains.add(pattern.slice(3));
+    } else {
+      this._blockedExact.add(pattern);
+    }
+  }
+  _uncacheBlockPattern(pattern) {
+    if (pattern.startsWith("*::")) {
+      this._blockedDomains.delete(pattern.slice(3));
+    } else {
+      this._blockedExact.delete(pattern);
+    }
+  }
+};
+
+// 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;
+  constructor(contactBook, trustPolicy) {
+    this._contactBook = contactBook;
+    this._trustPolicy = trustPolicy;
+  }
+  /**
+   * Create a handshake request envelope with embedded contact card.
+   *
+   * The payload is the JSON-serialized contact card, encrypted with
+   * SealedBox (anonymous encryption) to the recipient.
+   *
+   * Returns wire-format dict ready to send via transport.
+   */
+  async createHandshakeRequest(agent, toAddress, recipientVk) {
+    const card = await createContactCard(
+      agent.address,
+      agent._config.displayName,
+      agent._config.relayWsUrl,
+      agent._keyManager.signingKey
+    );
+    const cardJson = JSON.stringify(contactCardToDict(card));
+    const envelope = await createEnvelope(
+      agent.address,
+      toAddress,
+      "handshake.request" /* HANDSHAKE_REQUEST */,
+      new TextEncoder().encode(cardJson),
+      agent._keyManager.signingKey,
+      recipientVk
+    );
+    return toWireDict(envelope);
+  }
+  /**
+   * Handle an inbound handshake message.
+   *
+   * Returns null -- handshake messages are not user-visible.
+   */
+  async handleInbound(agent, envelope, senderVk) {
+    if (envelope.type === "handshake.request" /* HANDSHAKE_REQUEST */) {
+      await this._handleRequest(agent, envelope, senderVk);
+    } else if (envelope.type === "handshake.accept" /* HANDSHAKE_ACCEPT */) {
+      await this._handleAccept(agent, envelope, senderVk);
+    } else if (envelope.type === "handshake.deny" /* HANDSHAKE_DENY */) {
+    }
+    return null;
+  }
+  /**
+   * Process a handshake.request: decrypt contact card, apply trust policy.
+   */
+  async _handleRequest(agent, envelope, senderVk) {
+    const plaintext = decryptPayloadAnonymous(
+      envelope.payload,
+      agent._keyManager.signingKey
+    );
+    const cardDict = JSON.parse(
+      new TextDecoder().decode(plaintext)
+    );
+    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,
+        trustState: "provisional",
+        trustSource: "auto-accepted-provisional"
+      });
+      await this._sendAccept(agent, envelope.fromAddress, senderVk);
+    } else if (this._trustPolicy === "allowlist-only") {
+      await this._sendDeny(agent, envelope.fromAddress, senderVk);
+    } else {
+      this._contactBook.addPending(
+        envelope.fromAddress,
+        JSON.stringify(cardDict)
+      );
+    }
+  }
+  /**
+   * 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(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"
+    });
+    this._contactBook.setPinnedAt(envelope.fromAddress);
+  }
+  /**
+   * Send a handshake.accept envelope back to the requester.
+   */
+  async _sendAccept(agent, toAddress, recipientVk) {
+    const card = await createContactCard(
+      agent.address,
+      agent._config.displayName,
+      agent._config.relayWsUrl,
+      agent._keyManager.signingKey
+    );
+    const acceptPayload = JSON.stringify({
+      status: "accepted",
+      contact_card: contactCardToDict(card)
+    });
+    const envelope = await createEnvelope(
+      agent.address,
+      toAddress,
+      "handshake.accept" /* HANDSHAKE_ACCEPT */,
+      new TextEncoder().encode(acceptPayload),
+      agent._keyManager.signingKey,
+      recipientVk
+    );
+    const wire = toWireDict(envelope);
+    if (agent._transport) {
+      await agent._transport.send(wire);
+    }
+  }
+  /**
+   * Send a handshake.deny envelope to the requester.
+   */
+  async _sendDeny(agent, toAddress, recipientVk) {
+    const denyPayload = JSON.stringify({
+      status: "denied",
+      reason: "allowlist-only"
+    });
+    const envelope = await createEnvelope(
+      agent.address,
+      toAddress,
+      "handshake.deny" /* HANDSHAKE_DENY */,
+      new TextEncoder().encode(denyPayload),
+      agent._keyManager.signingKey,
+      recipientVk
+    );
+    const wire = toWireDict(envelope);
+    if (agent._transport) {
+      await agent._transport.send(wire);
+    }
+  }
+};
+
+// src/sdk/resolver-base.ts
+var AddressResolver = class {
+};
+
+// src/sdk/tier3.ts
+import { createPublicClient, http, defineChain } from "viem";
+var DEFAULT_RPC_URL = "https://sepolia.base.org";
+var DEFAULT_CHAIN_ID = 84532;
+var CACHE_TTL_MS = 3600 * 1e3;
+var REGISTRY_ABI = [
+  {
+    name: "resolve",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "name", type: "string" }],
+    outputs: [
+      { name: "owner", type: "address" },
+      { name: "publicKey", type: "string" },
+      { name: "relayUrl", type: "string" },
+      { name: "expiry", type: "uint256" }
+    ]
+  },
+  {
+    name: "available",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "name", type: "string" }],
+    outputs: [{ name: "", type: "bool" }]
+  }
+];
+function buildChain(chainId, rpcUrl) {
+  return defineChain({
+    id: chainId,
+    name: `chain-${chainId}`,
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    rpcUrls: {
+      default: { http: [rpcUrl] }
+    }
+  });
+}
+var Tier3Resolver = class extends AddressResolver {
+  _contractAddress;
+  _client;
+  _cacheTtlMs;
+  _cache = /* @__PURE__ */ new Map();
+  constructor(config) {
+    super();
+    this._contractAddress = config.contractAddress;
+    this._cacheTtlMs = config.cacheTtlMs ?? CACHE_TTL_MS;
+    const rpcUrl = config.rpcUrl ?? DEFAULT_RPC_URL;
+    const chainId = config.chainId ?? DEFAULT_CHAIN_ID;
+    this._client = createPublicClient({
+      chain: buildChain(chainId, rpcUrl),
+      transport: http(rpcUrl)
+    });
+  }
+  async resolvePublicKey(address, _token, _relayUrl) {
+    const parsed = parseAddress(address);
+    const name = parsed.domain;
+    const cached = this._cache.get(name);
+    if (cached && cached.expiresAt > Date.now()) {
+      return cached.publicKey;
+    }
+    try {
+      const result = await this._client.readContract({
+        address: this._contractAddress,
+        abi: REGISTRY_ABI,
+        functionName: "resolve",
+        args: [name]
+      });
+      const [_owner, publicKey, _relayUrl2, _expiry] = result;
+      if (!publicKey) {
+        throw new UAMError(
+          `Tier 3 name '${name}' has no public key registered`
+        );
+      }
+      this._cache.set(name, {
+        publicKey,
+        expiresAt: Date.now() + this._cacheTtlMs
+      });
+      return publicKey;
+    } catch (err) {
+      if (err instanceof UAMError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes("NameNotFound") || msg.includes("revert")) {
+        throw new UAMError(`Tier 3 name not found on-chain: ${name}`);
+      }
+      throw new UAMError(`Tier 3 resolution failed for ${name}: ${msg}`);
+    }
+  }
+  /**
+   * Check if a name is available for registration.
+   */
+  async isAvailable(name) {
+    try {
+      const result = await this._client.readContract({
+        address: this._contractAddress,
+        abi: REGISTRY_ABI,
+        functionName: "available",
+        args: [name]
+      });
+      return result;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Clear cache for a specific name or all names.
+   */
+  invalidateCache(name) {
+    if (name) {
+      this._cache.delete(name);
+    } else {
+      this._cache.clear();
+    }
+  }
+};
+
+// src/sdk/resolver.ts
+init_dns_verifier();
+var Tier1Resolver = class extends AddressResolver {
+  async resolvePublicKey(address, _token, relayUrl) {
+    const resp = await fetch(
+      `${relayUrl}/api/v1/agents/${address}/public-key`
+    );
+    if (resp.status === 404) {
+      throw new UAMError(`Agent not found: ${address}`);
+    }
+    if (!resp.ok) {
+      throw new UAMError(
+        `Resolver request failed: ${resp.status} ${resp.statusText}`
+      );
+    }
+    const data = await resp.json();
+    return data["public_key"];
+  }
+};
+var Tier2Resolver = class extends AddressResolver {
+  async resolvePublicKey(address, _token, _relayUrl) {
+    const parsed = parseAddress(address);
+    const txtRecords = await queryUamTxt(parsed.domain);
+    for (const txt of txtRecords) {
+      const tags = parseUamTxt(txt);
+      if (tags["v"] === "uam1") {
+        const key = extractPublicKey(tags);
+        if (key) return key;
+      }
+    }
+    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`
+    );
+  }
+};
+var SmartResolver = class extends AddressResolver {
+  relayDomain;
+  _tier1;
+  _tier2;
+  _tier3;
+  constructor(relayDomain, tier3Config) {
+    super();
+    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);
+    }
+    if (domain.includes(".")) {
+      return this._tier2.resolvePublicKey(address, token, relayUrl);
+    }
+    if (!this._tier3) {
+      throw new UAMError(
+        `Tier 3 resolution requires contract config. Cannot resolve dot-free domain: '${domain}'`
+      );
+    }
+    return this._tier3.resolvePublicKey(address, token, relayUrl);
+  }
+};
+
+// src/sdk/transport/base.ts
+var TransportBase = class {
+};
+
+// src/sdk/transport/http.ts
+var HTTPTransport = class extends TransportBase {
+  _relayUrl;
+  _token;
+  _address;
+  constructor(relayUrl, token, address) {
+    super();
+    this._relayUrl = relayUrl.replace(/\/+$/, "");
+    this._token = token;
+    this._address = address;
+  }
+  async connect() {
+  }
+  async disconnect() {
+  }
+  async send(envelope) {
+    const resp = await fetch(`${this._relayUrl}/api/v1/send`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this._token}`
+      },
+      body: JSON.stringify({ envelope })
+    });
+    if (!resp.ok) {
+      throw new Error(
+        `HTTP send failed: ${resp.status} ${resp.statusText}`
+      );
+    }
+  }
+  async receive(limit = 50) {
+    const url = new URL(
+      `${this._relayUrl}/api/v1/inbox/${this._address}`
+    );
+    url.searchParams.set("limit", String(limit));
+    const resp = await fetch(url.toString(), {
+      headers: {
+        Authorization: `Bearer ${this._token}`
+      }
+    });
+    if (!resp.ok) {
+      throw new Error(
+        `HTTP receive failed: ${resp.status} ${resp.statusText}`
+      );
+    }
+    const data = await resp.json();
+    return data["messages"] ?? [];
+  }
+  async listen(_callback) {
+    throw new Error(
+      "HTTP transport does not support real-time listening. Use receive() for polling or switch to WebSocket transport."
+    );
+  }
+};
+
+// src/sdk/transport/websocket.ts
+import WebSocket from "ws";
+var BASE_DELAY = 1;
+var MAX_DELAY = 60;
+var JITTER_RANGE = 1;
+var SEND_SETTLE_SECONDS = 5;
+var WebSocketTransport = class extends TransportBase {
+  _url;
+  _token;
+  _onMessage;
+  _ws = null;
+  _pending = [];
+  _connected = false;
+  _connectResolve = null;
+  _connectReject = null;
+  _running = false;
+  _reconnectTimeout = null;
+  /** Envelopes sent that the relay hasn't answered yet. */
+  _unanswered = 0;
+  _settling = null;
+  _settled = null;
+  /** @internal How long a close waits, in ms. Replaceable in tests. */
+  _settleMs = SEND_SETTLE_SECONDS * 1e3;
+  constructor(wsUrl, token, onMessage) {
+    super();
+    this._url = wsUrl;
+    this._token = token;
+    this._onMessage = onMessage ?? null;
+  }
+  async connect() {
+    this._running = true;
+    return new Promise((resolve, reject) => {
+      this._connectResolve = resolve;
+      this._connectReject = reject;
+      this._startConnectionLoop();
+      const timeout = setTimeout(() => {
+        this._connectReject = null;
+        this._connectResolve = null;
+        reject(new Error("WebSocket connection timeout (30s)"));
+      }, 3e4);
+      const origResolve = this._connectResolve;
+      this._connectResolve = () => {
+        clearTimeout(timeout);
+        origResolve?.();
+      };
+    });
+  }
+  /**
+   * 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);
+      this._reconnectTimeout = null;
+    }
+    if (this._ws) {
+      this._ws.removeAllListeners();
+      this._ws.close();
+      this._ws = null;
+    }
+    this._connected = false;
+  }
+  async send(envelope) {
+    if (!this._ws || this._ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket not connected");
+    }
+    this._ws.send(JSON.stringify(envelope));
+    this._unanswered += 1;
+  }
+  async receive(limit = 50) {
+    const result = this._pending.slice(0, limit);
+    this._pending = this._pending.slice(limit);
+    return result;
+  }
+  async listen(callback) {
+    this._onMessage = callback;
+  }
+  /** Resolves when nothing is unanswered, or after _settleMs regardless. */
+  _allAnswered() {
+    if (this._unanswered === 0) return Promise.resolve();
+    this._settling ??= new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        log.warn(`Closing with ${this._unanswered} sends unanswered`);
+        this._settled?.();
+      }, this._settleMs);
+      this._settled = () => {
+        clearTimeout(timeout);
+        this._settling = null;
+        this._settled = null;
+        resolve();
+      };
+    });
+    return this._settling;
+  }
+  _answered() {
+    this._unanswered = Math.max(0, this._unanswered - 1);
+    if (this._unanswered === 0) this._settled?.();
+  }
+  _startConnectionLoop() {
+    let attempt = 0;
+    const tryConnect = () => {
+      if (!this._running) return;
+      const ws = new WebSocket(this._url, [`bearer.${this._token}`]);
+      this._ws = ws;
+      ws.on("open", () => {
+        this._connected = true;
+        attempt = 0;
+        if (this._connectResolve) {
+          this._connectResolve();
+          this._connectResolve = null;
+          this._connectReject = null;
+        }
+      });
+      ws.on("message", (data) => {
+        try {
+          const msg = JSON.parse(data.toString());
+          this._handleMessage(msg);
+        } catch {
+        }
+      });
+      ws.on("close", () => {
+        this._connected = false;
+        this._ws = null;
+        this._unanswered = 0;
+        this._settled?.();
+        if (!this._running) return;
+        attempt += 1;
+        const delay = Math.min(BASE_DELAY * Math.pow(2, attempt), MAX_DELAY);
+        const jitter = Math.random() * JITTER_RANGE;
+        const totalDelay = (delay + jitter) * 1e3;
+        this._reconnectTimeout = setTimeout(tryConnect, totalDelay);
+      });
+      ws.on("error", (err) => {
+        if (this._connectReject && !this._connected) {
+        }
+      });
+    };
+    tryConnect();
+  }
+  _handleMessage(msg) {
+    const msgType = msg["type"];
+    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 === WebSocket.OPEN) {
+        this._ws.send(JSON.stringify({ type: "pong" }));
+      }
+    } else if (msgType === "ack") {
+      this._answered();
+    } else if (msgType === "error" || "error" in msg) {
+      this._answered();
+    }
+  }
+};
+
+// src/sdk/transport/index.ts
+function createTransport(config, token, address, onMessage) {
+  if (config.transportType === "http") {
+    return new HTTPTransport(config.relayUrl, token, address);
+  } else {
+    return new WebSocketTransport(config.relayWsUrl, token, onMessage);
+  }
+}
+
+// src/sdk/replay-cache.ts
+import { mkdirSync as mkdirSync3 } from "fs";
+import { dirname as dirname2 } from "path";
+import { setTimeout as sleep } from "timers/promises";
+import Database2 from "better-sqlite3";
+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 sleep(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() {
+    mkdirSync3(dirname2(this._path), { recursive: true });
+    const db = new Database2(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;
+  /** @internal */
+  _keyManager;
+  /** @internal */
+  _transport = null;
+  _resolver;
+  _address = null;
+  _token = null;
+  _connected = false;
+  _autoRegister;
+  /** @internal */
+  _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.
+   */
+  constructor(name, options) {
+    this._config = new SDKConfig({
+      name,
+      relayUrl: options?.relay,
+      relayDomain: options?.domain ?? void 0,
+      keyDir: options?.keyDir,
+      displayName: options?.displayName ?? name,
+      transportType: options?.transport ?? "websocket",
+      trustPolicy: options?.trustPolicy ?? "auto-accept"
+    });
+    this._keyManager = new KeyManager(this._config.keyDir);
+    this._resolver = new SmartResolver(this._config.relayDomain);
+    this._autoRegister = options?.autoRegister ?? true;
+    this._contactBook = new ContactBook(this._config.dataDir);
+    this._handshake = new HandshakeManager(
+      this._contactBook,
+      this._config.trustPolicy
+    );
+    this._replayCache = new PersistentReplayCache(
+      join4(this._config.dataDir, "replay", "replay.db"),
+      {
+        capacity: replayCacheCapacityFromEnv(),
+        now: () => this._clock()
+      }
+    );
+  }
+  // -- Properties ----------------------------------------------------------
+  /** The agent's full UAM address (e.g., 'myagent::youam.network'). */
+  get address() {
+    if (this._address === null) {
+      throw new Error(
+        "Agent not yet connected. Call await agent.connect() first."
+      );
+    }
+    return this._address;
+  }
+  /** UAM SDK version. */
+  get version() {
+    return SDK_VERSION;
+  }
+  /** The agent's public key (base64-encoded Ed25519 verify key). */
+  get publicKey() {
+    return serializeVerifyKey(this._keyManager.verifyKey);
+  }
+  /** Whether the agent has completed connection setup. */
+  get isConnected() {
+    return this._connected;
+  }
+  /**
+   * Generate and return a signed contact card for this agent.
+   */
+  async contactCard() {
+    if (!this._connected) {
+      throw new Error("Agent not connected. Call connect() first.");
+    }
+    const card = await createContactCard(
+      this._address,
+      this._config.displayName,
+      this._config.relayWsUrl,
+      this._keyManager.signingKey
+    );
+    return contactCardToDict(card);
+  }
+  // -- Lifecycle -----------------------------------------------------------
+  /**
+   * Initialize the agent: load/generate keys, register, connect transport.
+   *
+   * Idempotent -- calling twice is safe.
+   */
+  async connect() {
+    if (this._connected) {
+      return;
+    }
+    await sodiumReady;
+    this._keyManager.loadOrGenerate(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._useAddress(await this._storedAddress());
+    } else if (this._autoRegister) {
+      await this._registerWithRelay();
+    } else {
+      throw new UAMError(
+        "No stored token and autoRegister=false. Register manually or set autoRegister=true."
+      );
+    }
+    this._transport = createTransport(
+      this._config,
+      this._token,
+      this._address
+    );
+    await this._transport.connect();
+    this._contactBook.open();
+    this._connected = true;
+    await this._sweepExpiredHandshakes();
+  }
+  /**
+   * Disconnect the transport and clean up resources.
+   */
+  async close() {
+    this._contactBook.close();
+    await this._replayCache.close();
+    if (this._transport) {
+      await this._transport.disconnect();
+    }
+    this._connected = false;
+  }
+  // -- Messaging -----------------------------------------------------------
+  /**
+   * Send an encrypted, signed message. Returns the message_id.
+   */
+  async send(toAddress, message, options) {
+    await this._ensureConnected();
+    if (this._config.trustPolicy === "require_verify") {
+      const trust = this._contactBook.getTrustState(toAddress);
+      if (trust !== "pinned" && trust !== "verified") {
+        throw new UAMError(
+          `Trust policy 'require_verify' requires fingerprint verification before sending to ${toAddress}. Run: uam contact verify ${toAddress}`
+        );
+      }
+    }
+    const recipientVk = await this._resolvePublicKey(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(
+      this._address,
+      toAddress,
+      "message" /* MESSAGE */,
+      new TextEncoder().encode(message),
+      this._keyManager.signingKey,
+      recipientVk,
+      {
+        threadId: options?.threadId,
+        mediaType: "text/plain",
+        attachments: options?.attachments
+      }
+    );
+    const wire = toWireDict(envelope);
+    const relayUrls = await this._getRelayUrls(toAddress);
+    if (relayUrls !== null && relayUrls.length === 1 && relayUrls[0] === this._config.relayUrl) {
+      await this._transport.send(wire);
+    } else if (relayUrls !== null && relayUrls.length > 0) {
+      await this._trySendWithFailover(wire, relayUrls);
+    } else {
+      await this._transport.send(wire);
+    }
+    return envelope.messageId;
+  }
+  /**
+   * Retrieve, decrypt, and verify pending messages.
+   *
+   * Returns a list of ReceivedMessage data objects.
+   * 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();
+    await this._sweepExpiredHandshakes();
+    const rawMessages = await this._transport.receive(limit);
+    const result = [];
+    for (const raw of rawMessages) {
+      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);
+      }
+    }
+    return result;
+  }
+  // -- Trust management (HAND-02, HAND-04) ---------------------------------
+  /** List pending handshake requests. */
+  async pending() {
+    await this._ensureConnected();
+    return this._contactBook.getPending();
+  }
+  /**
+   * Approve a pending handshake request.
+   *
+   * Adds the sender to contacts with trust_source='explicit-approval'
+   * and sends handshake.accept back.
+   */
+  async approve(address) {
+    await this._ensureConnected();
+    const pendingList = this._contactBook.getPending();
+    const entry = pendingList.find((p) => p.address === address);
+    if (!entry) {
+      throw new UAMError(`No pending handshake from ${address}`);
+    }
+    const cardDict = JSON.parse(entry.contactCard);
+    const card = contactCardFromDict(cardDict);
+    verifyContactCard(card);
+    const senderVk = deserializeVerifyKey(card.publicKey);
+    bindCardToEnvelope(card, { fromAddress: address }, senderVk);
+    this._contactBook.addContact(card.address, card.publicKey, {
+      displayName: card.displayName,
+      trustState: "trusted",
+      trustSource: "explicit-approval"
+    });
+    this._contactBook.removePending(address);
+    await this._handshake._sendAccept(this, address, senderVk);
+  }
+  /**
+   * Deny a pending handshake request.
+   *
+   * Removes the entry from pending and sends handshake.deny.
+   */
+  async deny(address) {
+    await this._ensureConnected();
+    const pendingList = this._contactBook.getPending();
+    const entry = pendingList.find((p) => p.address === address);
+    if (!entry) {
+      throw new UAMError(`No pending handshake from ${address}`);
+    }
+    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);
+  }
+  /**
+   * Block an address or domain pattern (HAND-04).
+   */
+  async block(pattern) {
+    await this._ensureConnected();
+    this._contactBook.addBlock(pattern);
+  }
+  /**
+   * Remove a block pattern (HAND-04).
+   */
+  async unblock(pattern) {
+    await this._ensureConnected();
+    this._contactBook.removeBlock(pattern);
+  }
+  // -- Domain verification (DNS-02) ----------------------------------------
+  /**
+   * Verify domain ownership via relay endpoint (DNS-02).
+   *
+   * Polls `POST /api/v1/verify-domain` until the relay confirms
+   * DNS TXT (or HTTPS fallback) verification succeeds, or timeout
+   * elapses.
+   *
+   * Returns `true` if verified, `false` on timeout.
+   */
+  async verifyDomain(domain, options) {
+    const { generateTxtRecord: generateTxtRecord2 } = await Promise.resolve().then(() => (init_dns_verifier(), dns_verifier_exports));
+    await this._ensureConnected();
+    const timeout = options?.timeout ?? 3e5;
+    const pollInterval = options?.pollInterval ?? 1e4;
+    const expectedTxt = generateTxtRecord2(
+      this.publicKey,
+      this._config.relayUrl
+    );
+    void expectedTxt;
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      try {
+        const resp = await fetch(
+          `${this._config.relayUrl}/api/v1/verify-domain`,
+          {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${this._token}`
+            },
+            body: JSON.stringify({ domain }),
+            signal: AbortSignal.timeout(3e4)
+          }
+        );
+        if (resp.ok) {
+          const result = await resp.json();
+          if (result["status"] === "verified") {
+            return true;
+          }
+        }
+      } catch {
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    return false;
+  }
+  // -- Internal methods ----------------------------------------------------
+  /** Multi-relay failover (CARD-06). */
+  async _getRelayUrls(toAddress) {
+    const urls = this._contactBook.getRelayUrls(toAddress);
+    if (urls !== null) {
+      return urls;
+    }
+    return [this._config.relayUrl];
+  }
+  /**
+   * Try sending wire envelope to each relay URL in order (CARD-06).
+   *
+   * Uses transient fetch POST requests so the envelope can be delivered
+   * to any relay that hosts the recipient.
+   */
+  async _trySendWithFailover(wire, relayUrls) {
+    let lastError = null;
+    for (const url of relayUrls) {
+      let base = url.replace(/\/+$/, "");
+      if (base.endsWith("/ws")) {
+        base = base.slice(0, -3);
+      }
+      base = base.replace("wss://", "https://").replace("ws://", "http://");
+      const sendUrl = `${base}/api/v1/send`;
+      try {
+        const resp = await fetch(sendUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this._token}`
+          },
+          body: JSON.stringify({ envelope: wire }),
+          signal: AbortSignal.timeout(1e4)
+        });
+        if (!resp.ok) {
+          throw new Error(`HTTP ${resp.status}`);
+        }
+        return;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    if (lastError !== null) {
+      throw lastError;
+    }
+    throw new UAMError("No relay URLs to try");
+  }
+  async _ensureConnected() {
+    if (!this._connected) {
+      await this.connect();
+    }
+  }
+  /**
+   * 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.
+   */
+  async _resolvePublicKey(toAddress) {
+    const pkStr = this._contactBook.getPublicKey(toAddress);
+    if (pkStr !== null) {
+      return deserializeVerifyKey(pkStr);
+    }
+    const resolvedPkStr = await this._resolver.resolvePublicKey(
+      toAddress,
+      this._token,
+      this._config.relayUrl
+    );
+    const storedPk = this._contactBook.getPublicKey(toAddress);
+    if (storedPk !== null && storedPk !== resolvedPkStr) {
+      const trust = this._contactBook.getTrustState(toAddress);
+      if (trust === "pinned" || trust === "trusted" || trust === "verified") {
+        throw new KeyPinningError(
+          `CRITICAL: Public key mismatch for ${toAddress}! Stored key does not match resolved key. This may indicate a relay MITM attack. To accept the new key: uam contact remove ${toAddress}`
+        );
+      }
+    }
+    return deserializeVerifyKey(resolvedPkStr);
+  }
+  async _initiateHandshake(toAddress, recipientVk) {
+    const wire = await this._handshake.createHandshakeRequest(
+      this,
+      toAddress,
+      recipientVk
+    );
+    await this._transport.send(wire);
+    this._contactBook.addContact(
+      toAddress,
+      serializeVerifyKey(recipientVk),
+      { trustState: "handshake-sent" }
+    );
+  }
+  /**
+   * Process a single inbound envelope: verify, decrypt, handle handshakes.
+   *
+   * Returns null for invalid messages or handshake protocol messages.
+   */
+  async _processInbound(raw) {
+    const envelope = fromWireDict(raw);
+    if (this._contactBook.isBlocked(envelope.fromAddress)) {
+      return null;
+    }
+    let senderPkStr = this._contactBook.getPublicKey(envelope.fromAddress);
+    if (senderPkStr === null) {
+      try {
+        senderPkStr = await this._resolver.resolvePublicKey(
+          envelope.fromAddress,
+          this._token,
+          this._config.relayUrl
+        );
+      } catch {
+        return null;
+      }
+    }
+    const senderVk = deserializeVerifyKey(senderPkStr);
+    try {
+      verifyEnvelope(envelope, senderVk);
+    } catch (err) {
+      if (err instanceof SignatureVerificationError) {
+        return null;
+      }
+      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);
+    }
+    if (this._handshake._trustPolicy !== "auto-accept") {
+      if (!this._contactBook.isTrustedOrVerified(envelope.fromAddress)) {
+        return null;
+      }
+    }
+    let plaintextBytes;
+    try {
+      plaintextBytes = decryptPayload(
+        envelope.payload,
+        this._keyManager.signingKey,
+        senderVk
+      );
+    } catch (err) {
+      if (err instanceof DecryptionError) {
+        return null;
+      }
+      throw err;
+    }
+    return Object.freeze({
+      messageId: envelope.messageId,
+      fromAddress: envelope.fromAddress,
+      toAddress: envelope.toAddress,
+      content: new TextDecoder().decode(plaintextBytes),
+      timestamp: envelope.timestamp,
+      type: envelope.type,
+      threadId: envelope.threadId,
+      replyTo: envelope.replyTo,
+      mediaType: envelope.mediaType,
+      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).
+   */
+  async _sweepExpiredHandshakes() {
+    const expired = this._contactBook.getExpiredPending(7);
+    for (const entry of expired) {
+      try {
+        const cardDict = JSON.parse(entry.contactCard);
+        const card = contactCardFromDict(cardDict);
+        const recipientVk = deserializeVerifyKey(card.publicKey);
+        const failPayload = JSON.stringify({
+          reason: "handshake_expired",
+          original_from: entry.address
+        });
+        const envelope = await createEnvelope(
+          this._address,
+          entry.address,
+          "receipt.failed" /* RECEIPT_FAILED */,
+          new TextEncoder().encode(failPayload),
+          this._keyManager.signingKey,
+          recipientVk
+        );
+        const wire = toWireDict(envelope);
+        await this._transport.send(wire);
+      } catch {
+      }
+      this._contactBook.removePending(entry.address);
+    }
+  }
+  /**
+   * Send receipt.read back to the sender (RCPT-01).
+   *
+   * Fire-and-forget: errors are never propagated.
+   * Anti-loop guard: receipts, handshakes, and session messages are skipped.
+   */
+  async _sendReadReceipt(msg) {
+    if (msg.type.startsWith("receipt.") || msg.type.startsWith("handshake.") || msg.type.startsWith("session.")) {
+      return;
+    }
+    try {
+      const senderPkStr = this._contactBook.getPublicKey(msg.fromAddress);
+      if (senderPkStr === null) return;
+      const senderVk = deserializeVerifyKey(senderPkStr);
+      const receiptPayload = JSON.stringify({
+        message_id: msg.messageId
+      });
+      const envelope = await createEnvelope(
+        this._address,
+        msg.fromAddress,
+        "receipt.read" /* RECEIPT_READ */,
+        new TextEncoder().encode(receiptPayload),
+        this._keyManager.signingKey,
+        senderVk,
+        { replyTo: msg.messageId }
+      );
+      const wire = toWireDict(envelope);
+      await this._transport.send(wire);
+    } catch {
+    }
+  }
+  /**
+   * Register with the relay server.
+   *
+   * 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 body = {
+      agent_name: this._config.name,
+      public_key: serializeVerifyKey(this._keyManager.verifyKey)
+    };
+    let resp = await this._postRegistration(body);
+    if (resp.status === 409) {
+      const address2 = await this._addressOnRelay();
+      resp = await this._postRegistration({
+        ...body,
+        proof: this._registrationProof(address2)
+      });
+      if (resp.status === 409 || resp.status === 403) {
+        throw this._ownershipNotProven(address2);
+      }
+    }
+    if (!resp.ok) {
+      const text = await resp.text();
+      throw new UAMError(
+        `Registration failed: ${resp.status} ${text}`
+      );
+    }
+    const data = await resp.json();
+    const address = data["address"];
+    this._useAddress(address);
+    this._token = data["token"];
+    const { name } = this._config;
+    const token = this._token;
+    this._tryToSave("token", () => this._keyManager.saveToken(name, token));
+    this._saveAddress(address);
+  }
+  /** This agent's address on the relay, for signing a proof. */
+  async _addressOnRelay() {
+    const { name, explicitRelayDomain, relayDomain, relayUrl } = this._config;
+    if (explicitRelayDomain !== null) return `${name}::${explicitRelayDomain}`;
+    const domain = await this._fetchRelayDomain();
+    if (domain === null) return `${name}::${relayDomain}`;
+    if (!this._relayMayUse(domain)) {
+      throw new UAMError(
+        `The relay at ${relayUrl} says its domain is ${domain}. Pass the domain option as ${JSON.stringify(domain)} if that is right.`
+      );
+    }
+    return `${name}::${domain}`;
+  }
+  /**
+   * True if the relay's URL fits `domain`, so a proof can be signed for it.
+   *
+   * A proof names an address on one relay, so it is only signed for a domain
+   * this URL belongs to. A relay on this machine may use any domain.
+   */
+  _relayMayUse(domain) {
+    let host;
+    try {
+      host = new URL(this._config.relayUrl).hostname.toLowerCase();
+    } catch {
+      return false;
+    }
+    const wanted = domain.toLowerCase();
+    return host === wanted || host.endsWith(`.${wanted}`) || host === "localhost" || host === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(host);
+  }
+  _postRegistration(body) {
+    return fetch(`${this._config.relayUrl}/api/v1/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+  }
+  /**
+   * Sign a statement that this agent holds the key for `address`.
+   *
+   * The signed string must stay byte-identical to the Python SDK's.
+   */
+  _registrationProof(address) {
+    const timestamp = utcTimestamp();
+    const signature = signMessage(
+      new TextEncoder().encode(`uam-register-v1
+${address}
+${timestamp}`),
+      this._keyManager.signingKey
+    );
+    return { timestamp, signature };
+  }
+  _ownershipNotProven(address) {
+    return new UAMError(
+      `Address already registered, and this key could not prove ownership: ` + address
+    );
+  }
+  /** Remember `address` for this relay, if the key folder allows it. */
+  _saveAddress(address) {
+    const { name, relayUrl } = this._config;
+    this._tryToSave(
+      "address",
+      () => this._keyManager.saveAddress(name, address, relayUrl)
+    );
+  }
+  /** Saving is best effort: a key folder we can't write doesn't stop us. */
+  _tryToSave(what, save) {
+    try {
+      save();
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      log.warn(`Could not save the ${what}: ${reason}`);
+    }
+  }
+  /** Take `address` as ours; its domain is this relay's real domain. */
+  _useAddress(address) {
+    this._address = address;
+    const domain = parseAddress(address).domain;
+    this._config.relayDomain = domain;
+    if (this._resolver instanceof SmartResolver) {
+      this._resolver.relayDomain = domain;
+    }
+  }
+  /**
+   * The address the stored token belongs to.
+   *
+   * An explicit domain settles it. Otherwise the relay chooses the domain,
+   * and it need not be the relay's hostname: use the address saved for this
+   * relay, or ask the relay once and keep the answer.
+   */
+  async _storedAddress() {
+    const { name, explicitRelayDomain } = this._config;
+    if (explicitRelayDomain !== null) return `${name}::${explicitRelayDomain}`;
+    const saved = this._keyManager.loadAddress(name, this._config.relayUrl);
+    if (saved) return saved;
+    const domain = await this._fetchRelayDomain();
+    if (domain === null) return `${name}::${this._config.relayDomain}`;
+    const address = `${name}::${domain}`;
+    this._saveAddress(address);
+    return address;
+  }
+  /** Ask the relay for its domain; null if it cannot say. */
+  async _fetchRelayDomain() {
+    const url = `${this._config.relayUrl}/.well-known/uam-relay.json`;
+    try {
+      const resp = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+      if (!resp.ok) return null;
+      const data = await resp.json();
+      const domain = data["relay_domain"];
+      if (typeof domain !== "string" || domain === "") return null;
+      return parseAddress(`${this._config.name}::${domain}`).domain;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/sdk/webhook-verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(payload, signatureHeader, secret) {
+  if (!signatureHeader.startsWith("sha256=")) {
+    return false;
+  }
+  const expected = createHmac("sha256", secret).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 timingSafeEqual(expectedBuf, receivedBuf);
+}
+
+// src/sdk/index.ts
+init_dns_verifier();
+export {
+  Agent,
+  ContactBook,
+  protocol_exports as protocol,
+  verifyWebhookSignature
+};
+//# sourceMappingURL=index.js.map