@youam/sdk 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,2244 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/sdk/dns-verifier.ts
+var dns_verifier_exports = {};
+__export(dns_verifier_exports, {
+  extractPublicKey: () => extractPublicKey,
+  generateTxtRecord: () => generateTxtRecord,
+  parseUamTxt: () => parseUamTxt,
+  queryUamTxt: () => queryUamTxt,
+  resolveKeyViaHttps: () => resolveKeyViaHttps
+});
+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 (0, import_promises.resolveTxt)(`_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 import_promises;
+var init_dns_verifier = __esm({
+  "src/sdk/dns-verifier.ts"() {
+    "use strict";
+    import_promises = require("dns/promises");
+  }
+});
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Agent: () => Agent,
+  protocol: () => protocol_exports
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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_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 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
+var import_libsodium_wrappers = __toESM(require("libsodium-wrappers"), 1);
+var import_node_crypto = require("crypto");
+var sodiumReady = import_libsodium_wrappers.default.ready;
+function generateKeypair() {
+  const seed = import_libsodium_wrappers.default.randombytes_buf(32);
+  const kp = import_libsodium_wrappers.default.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 = import_libsodium_wrappers.default.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 (0, import_node_crypto.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 = import_libsodium_wrappers.default.crypto_sign_detached(data, signingKey);
+  return b64Encode(signature);
+}
+function verifySignature(data, signatureB64, verifyKey) {
+  try {
+    const sigBytes = b64Decode(signatureB64);
+    const valid = import_libsodium_wrappers.default.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(import_libsodium_wrappers.default.randombytes_buf(24));
+}
+function encryptPayload(plaintext, senderSigningKey, recipientVerifyKey) {
+  try {
+    const senderCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_sk_to_curve25519(senderSigningKey);
+    const recipientCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_pk_to_curve25519(recipientVerifyKey);
+    const nonce = import_libsodium_wrappers.default.randombytes_buf(import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
+    const encrypted = import_libsodium_wrappers.default.crypto_box_easy(plaintext, nonce, recipientCurve, senderCurve);
+    const combined = new Uint8Array(nonce.length + encrypted.length);
+    combined.set(nonce, 0);
+    combined.set(encrypted, nonce.length);
+    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, import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
+    const ciphertext = combined.slice(import_libsodium_wrappers.default.crypto_box_NONCEBYTES);
+    const recipientCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_sk_to_curve25519(recipientSigningKey);
+    const senderCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_pk_to_curve25519(senderVerifyKey);
+    return import_libsodium_wrappers.default.crypto_box_open_easy(ciphertext, nonce, senderCurve, recipientCurve);
+  } catch (err) {
+    if (err instanceof DecryptionError) throw err;
+    throw new DecryptionError(err instanceof Error ? err.message : String(err));
+  }
+}
+function encryptPayloadAnonymous(plaintext, recipientVerifyKey) {
+  const recipientCurve = import_libsodium_wrappers.default.crypto_sign_ed25519_pk_to_curve25519(recipientVerifyKey);
+  const ciphertext = import_libsodium_wrappers.default.crypto_box_seal(plaintext, recipientCurve);
+  return b64Encode(ciphertext);
+}
+function decryptPayloadAnonymous(ciphertextB64, recipientSigningKey) {
+  try {
+    const ciphertext = b64Decode(ciphertextB64);
+    const recipientCurveSk = import_libsodium_wrappers.default.crypto_sign_ed25519_sk_to_curve25519(recipientSigningKey);
+    const recipientVerifyKey = recipientSigningKey.slice(32);
+    const recipientCurvePk = import_libsodium_wrappers.default.crypto_sign_ed25519_pk_to_curve25519(recipientVerifyKey);
+    return import_libsodium_wrappers.default.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
+var import_node_crypto2 = require("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 = (0, import_node_crypto2.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/sdk/config.ts
+var import_node_os = require("os");
+var import_node_path = require("path");
+var DEFAULT_RELAY_URL = "https://relay.youam.network";
+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;
+  constructor(options) {
+    this.name = options.name;
+    this.relayUrl = 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"];
+    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 || (0, import_node_path.join)((0, import_node_os.homedir)(), ".uam");
+    this.keyDir = options.keyDir ?? (0, import_node_path.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/key-manager.ts
+var import_node_fs = require("fs");
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var import_node_os2 = require("os");
+var import_node_os3 = require("os");
+var DEFAULT_KEY_DIR = (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".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;
+    }
+    (0, import_node_fs.mkdirSync)(this._keyDir, { recursive: true });
+    const keyPath = (0, import_node_path2.join)(this._keyDir, `${name}.key`);
+    const pubPath = (0, import_node_path2.join)(this._keyDir, `${name}.pub`);
+    if ((0, import_node_fs2.existsSync)(keyPath)) {
+      this._checkPermissions(keyPath);
+      const seedB64 = (0, import_node_fs.readFileSync)(keyPath, "utf-8").trim();
+      this._keypair = deserializeSigningKey(seedB64);
+    } else {
+      this._keypair = generateKeypair();
+      (0, import_node_fs.writeFileSync)(keyPath, serializeSigningKey(this._keypair.seed));
+      (0, import_node_fs.writeFileSync)(pubPath, serializeVerifyKey(this._keypair.verifyKey));
+      this._setPermissions(keyPath);
+    }
+  }
+  /**
+   * Store the relay token alongside the keypair.
+   */
+  saveToken(name, token) {
+    (0, import_node_fs.mkdirSync)(this._keyDir, { recursive: true });
+    const tokenPath = (0, import_node_path2.join)(this._keyDir, `${name}.token`);
+    (0, import_node_fs.writeFileSync)(tokenPath, token);
+    this._setPermissions(tokenPath);
+  }
+  /**
+   * 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.
+   */
+  loadToken(name) {
+    const envToken = process.env["UAM_TOKEN"];
+    if (envToken) {
+      return envToken.trim();
+    }
+    const tokenPath = (0, import_node_path2.join)(this._keyDir, `${name}.token`);
+    if ((0, import_node_fs2.existsSync)(tokenPath)) {
+      return (0, import_node_fs.readFileSync)(tokenPath, "utf-8").trim();
+    }
+    const legacyPath = (0, import_node_path2.join)(this._keyDir, `${name}.api_key`);
+    if ((0, import_node_fs2.existsSync)(legacyPath)) {
+      return (0, import_node_fs.readFileSync)(legacyPath, "utf-8").trim();
+    }
+    return null;
+  }
+  /** Set file permissions to 0o600 (owner read/write only). */
+  _setPermissions(path) {
+    if ((0, import_node_os3.platform)() !== "win32") {
+      (0, import_node_fs.chmodSync)(path, 384);
+    }
+  }
+  /** Warn if key file permissions are too permissive. */
+  _checkPermissions(path) {
+    if ((0, import_node_os3.platform)() === "win32") {
+      return;
+    }
+    try {
+      const mode = (0, import_node_fs.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
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
+var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var ContactBook = class {
+  _dbPath;
+  _db = null;
+  _knownAddresses = /* @__PURE__ */ new Set();
+  _blockedExact = /* @__PURE__ */ new Set();
+  _blockedDomains = /* @__PURE__ */ new Set();
+  constructor(dataDir) {
+    this._dbPath = (0, import_node_path3.join)(dataDir, "contacts", "contacts.db");
+  }
+  /**
+   * Open the database, create tables, run migrations, load caches.
+   */
+  open() {
+    (0, import_node_fs3.mkdirSync)((0, import_node_path3.dirname)(this._dbPath), { recursive: true });
+    this._db = new import_better_sqlite3.default(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).
+   */
+  addContact(address, publicKey, options) {
+    if (this._db === null) {
+      throw new Error("ContactBook not open. Call open() first.");
+    }
+    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
+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(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);
+    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).
+   */
+  async _handleAccept(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/tier3.ts
+var import_viem = require("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 (0, import_viem.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 = (0, import_viem.createPublicClient)({
+      chain: buildChain(chainId, rpcUrl),
+      transport: (0, import_viem.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 AddressResolver = class {
+};
+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
+var import_ws = __toESM(require("ws"), 1);
+var BASE_DELAY = 1;
+var MAX_DELAY = 60;
+var JITTER_RANGE = 1;
+var WebSocketTransport = class extends TransportBase {
+  _url;
+  _onMessage;
+  _ws = null;
+  _pending = [];
+  _connected = false;
+  _connectResolve = null;
+  _connectReject = null;
+  _running = false;
+  _reconnectTimeout = null;
+  constructor(wsUrl, token, onMessage) {
+    super();
+    this._url = `${wsUrl}?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?.();
+      };
+    });
+  }
+  async disconnect() {
+    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 !== import_ws.default.OPEN) {
+      throw new Error("WebSocket not connected");
+    }
+    this._ws.send(JSON.stringify(envelope));
+  }
+  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;
+  }
+  _startConnectionLoop() {
+    let attempt = 0;
+    const tryConnect = () => {
+      if (!this._running) return;
+      const ws = new import_ws.default(this._url);
+      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;
+        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 (msgType === "ping") {
+      if (this._ws && this._ws.readyState === import_ws.default.OPEN) {
+        this._ws.send(JSON.stringify({ type: "pong" }));
+      }
+    } else if (msgType === "ack") {
+    } else if (msgType === "error" || "error" in msg) {
+    } else if ("uam_version" in msg) {
+      if (this._onMessage) {
+        this._onMessage(msg).catch(() => {
+        });
+      } else {
+        this._pending.push(msg);
+      }
+    }
+  }
+};
+
+// 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/agent.ts
+var Agent = class {
+  /** @internal */
+  _config;
+  /** @internal */
+  _keyManager;
+  /** @internal */
+  _transport = null;
+  _resolver;
+  _address = null;
+  _token = null;
+  _connected = false;
+  _autoRegister;
+  /** @internal */
+  _contactBook;
+  /** @internal */
+  _handshake;
+  /**
+   * 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
+    );
+  }
+  // -- 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 "0.1.0";
+  }
+  /** 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);
+    const storedToken = this._keyManager.loadToken(this._config.name);
+    if (storedToken) {
+      this._token = storedToken;
+      this._address = `${this._config.name}::${this._config.relayDomain}`;
+    } 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();
+    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);
+    if (!this._contactBook.isKnown(toAddress)) {
+      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.
+   * Silently drops messages with invalid signatures or decryption errors.
+   */
+  async inbox(limit = 50) {
+    await this._ensureConnected();
+    await this._sweepExpiredHandshakes();
+    const rawMessages = await this._transport.receive(limit);
+    const result = [];
+    for (const raw of rawMessages) {
+      const msg = await this._processInbound(raw);
+      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);
+    this._contactBook.addContact(card.address, card.publicKey, {
+      displayName: card.displayName,
+      trustState: "trusted",
+      trustSource: "explicit-approval"
+    });
+    this._contactBook.removePending(address);
+    const senderVk = deserializeVerifyKey(card.publicKey);
+    await this._handshake._sendAccept(this, address, senderVk);
+  }
+  /**
+   * 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.
+   *
+   * 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}`
+        );
+      }
+    }
+    this._contactBook.addContact(toAddress, resolvedPkStr, {
+      trustState: "provisional"
+    });
+    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 (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
+    });
+  }
+  /**
+   * 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
+      );
+      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.
+   * Stores the returned API key on disk.
+   */
+  async _registerWithRelay() {
+    const publicKeyStr = serializeVerifyKey(this._keyManager.verifyKey);
+    const resp = await fetch(
+      `${this._config.relayUrl}/api/v1/register`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          agent_name: this._config.name,
+          public_key: publicKeyStr
+        })
+      }
+    );
+    if (resp.status === 409) {
+      throw new UAMError(
+        `Address already registered with a different key: ${this._config.name}::${this._config.relayDomain}`
+      );
+    }
+    if (!resp.ok) {
+      const text = await resp.text();
+      throw new UAMError(
+        `Registration failed: ${resp.status} ${text}`
+      );
+    }
+    const data = await resp.json();
+    this._address = data["address"];
+    this._token = data["token"];
+    this._keyManager.saveToken(this._config.name, this._token);
+  }
+};
+
+// src/sdk/webhook-verify.ts
+var import_node_crypto3 = require("crypto");
+
+// src/sdk/index.ts
+init_dns_verifier();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Agent,
+  protocol
+});
+//# sourceMappingURL=index.cjs.map