@youam/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,9 +1,3 @@
-/**
- * SDK configuration (matching Python config.py).
- *
- * Priority (highest wins): constructor arg > env var > default.
- * TOML config file support is Python-only for now (unnecessary complexity for TS MVP).
- */
 declare class SDKConfig {
     readonly name: string;
     readonly relayUrl: string;
@@ -13,7 +7,9 @@ declare class SDKConfig {
     readonly displayName: string;
     readonly transportType: string;
     readonly trustPolicy: string;
-    readonly relayDomain: string;
+    relayDomain: string;
+    /** The domain the caller chose, if any; null when only derived. */
+    readonly explicitRelayDomain: string | null;
     constructor(options: {
         name: string;
         relayUrl?: string | null;
@@ -34,6 +30,12 @@ declare class SDKConfig {
 declare const UAM_VERSION = "0.1";
 /** Maximum envelope size in bytes (64 KB). */
 declare const MAX_ENVELOPE_SIZE = 65536;
+/**
+ * Maximum allowed skew, in seconds, between an inbound envelope's signed
+ * timestamp and the receiver's clock (either direction). Also the TTL of
+ * the inbound replay cache. Matches Python MAX_ENVELOPE_AGE.
+ */
+declare const MAX_ENVELOPE_AGE = 300;
 /** All UAM message types. */
 declare enum MessageType {
     MESSAGE = "message",
@@ -106,6 +108,18 @@ declare class InvalidContactCardError extends UAMError {
 declare class KeyPinningError extends UAMError {
     constructor(message?: string);
 }
+/**
+ * The relay refused a message sent over WebSocket.
+ *
+ * `code` is the relay's error code (e.g. "rate_limited"), `detail` its
+ * explanation. Over HTTP the same refusal is an HTTP error.
+ */
+declare class SendRefusedError extends UAMError {
+    readonly messageId: string;
+    readonly code: string;
+    readonly detail: string | undefined;
+    constructor(messageId: string, code: string, detail?: string);
+}
 
 /**
  * UAM address parsing and validation.
@@ -376,6 +390,119 @@ declare function createContactCard(address: string, displayName: string, relay:
  */
 declare function verifyContactCard(card: ContactCard): void;
 
+/**
+ * Signed owner objects: profile, canonical form, hash and schemas.
+ *
+ * Mirrors uam.protocol.signed in the Python SDK; both are checked against
+ * the same vectors (tests/vectors/signed/). Every owner object (key log
+ * entries, links, invites, redemptions, grants) is a JSON body in a
+ * restricted profile, hashed as
+ *
+ *     h = base64url(SHA-256("UAM-<type>-v1\n" || JCS(body)))   (no padding)
+ *
+ * The profile: printable ASCII strings, integers within +/-(2^53-1), no
+ * floats, no nulls, no duplicate keys, and no members a type doesn't define
+ * (new ones go under `ext`, with `crit` naming those a verifier must know).
+ * A body that breaks any rule is refused, never repaired.
+ */
+
+type Body = Record<string, unknown>;
+/** A signed-object body outside the profile or its type's schema. */
+declare class SignedObjectError extends UAMError {
+    constructor(message?: string);
+}
+/** Parse a body, refusing anything outside the profile. */
+declare function parseBody(text: string | Uint8Array): Body;
+/** RFC 8785 canonical form (inside the profile: sorted keys, no whitespace). */
+declare function canonical(body: Body): Uint8Array;
+/** The object's hash; the body is validated first. */
+declare function objectHash(body: Body): string;
+/** Refuse a body outside the profile or its type's schema. */
+declare function validate(body: unknown): asserts body is Body;
+
+/**
+ * did:key for the two key types owner objects carry (as the Python SDK).
+ *
+ * Ed25519 (an agent's key, `did:key:z6Mk...`, multicodec 0xed) and P-256
+ * (a passkey, `did:key:zDn...`, multicodec 0x1200, compressed point).
+ */
+
+type DidKeyKind = "ed25519" | "p256";
+/** A did:key string that isn't one of the two supported key types. */
+declare class InvalidDidKeyError extends UAMError {
+    constructor(message?: string);
+}
+/** `did:key:z...` for an Ed25519 key (32 bytes) or a compressed P-256 point (33 bytes). */
+declare function encodeDidKey(kind: DidKeyKind, publicKey: Uint8Array): string;
+/** The key type and raw public key in a did:key string. */
+declare function decodeDidKey(did: string): {
+    kind: DidKeyKind;
+    key: Uint8Array;
+};
+
+/**
+ * Passkeys (WebAuthn): registration, assertions and the approval challenge.
+ *
+ * Mirrors uam.protocol.webauthn in the Python SDK; both are checked against
+ * the same vectors (tests/vectors/webauthn/).
+ *
+ * - registration: `webauthn.create`, attestation format `none` only, user
+ *   present and verified, ES256 only;
+ * - assertion: `webauthn.get`, the exact challenge, the owner origin exactly,
+ *   no cross-origin frame, rpIdHash = SHA-256(RP ID), user present and
+ *   verified, backup eligibility unchanged, an ES256 signature over
+ *   `authenticatorData || SHA-256(clientDataJSON)` (high-S accepted), and,
+ *   where the stored counter is known, a counter that went up whenever either
+ *   count is non-zero (synced passkeys report 0 throughout; a count that
+ *   drops to 0 may be a clone).
+ *
+ * ES256 only: a passkey's did:key must never look like an agent key.
+ */
+
+/** A registration or assertion that fails a check. */
+declare class WebAuthnError extends UAMError {
+    constructor(message?: string);
+}
+/** A registered passkey: its id, algorithm, compressed P-256 key and flags. */
+interface Credential {
+    readonly id: Uint8Array;
+    readonly alg: number;
+    readonly publicKey: Uint8Array;
+    readonly backupEligible: boolean;
+    readonly signCount: number;
+}
+declare function credentialDid(credential: Credential): string;
+/** Check a `webauthn.create` response; the passkey it registers. */
+declare function verifyRegistration(args: {
+    attestationObject: Uint8Array;
+    clientDataJSON: Uint8Array;
+    challenge: Uint8Array;
+    origin: string;
+    rpId: string;
+}): Credential;
+/**
+ * Check a `webauthn.get` response from `credential`; its new sign count.
+ *
+ * `checkCounter: false` is for a verifier without the stored counter (an
+ * agent checking an approval offline); the relay always checks it.
+ */
+declare function verifyAssertion(credential: Credential, args: {
+    authenticatorData: Uint8Array;
+    clientDataJSON: Uint8Array;
+    signature: Uint8Array;
+    challenge: Uint8Array;
+    origin: string;
+    rpId: string;
+    checkCounter?: boolean;
+}): number;
+/**
+ * The challenge one Face ID signs to approve `items` (type, hash) as shown.
+ *
+ * `screen` is the exact text the page showed; the challenge commits to its
+ * SHA-256, so the page can't show one thing and get another signed.
+ */
+declare function approvalChallenge(items: Array<[string, string]>, screen: string): Uint8Array;
+
 /**
  * UAM Protocol -- Universal Agent Messaging protocol library.
  *
@@ -386,6 +513,7 @@ type index_Address = Address;
 type index_ContactCard = ContactCard;
 type index_DecryptionError = DecryptionError;
 declare const index_DecryptionError: typeof DecryptionError;
+type index_DidKeyKind = DidKeyKind;
 type index_EncryptionError = EncryptionError;
 declare const index_EncryptionError: typeof EncryptionError;
 type index_EnvelopeTooLargeError = EnvelopeTooLargeError;
@@ -394,42 +522,58 @@ type index_InvalidAddressError = InvalidAddressError;
 declare const index_InvalidAddressError: typeof InvalidAddressError;
 type index_InvalidContactCardError = InvalidContactCardError;
 declare const index_InvalidContactCardError: typeof InvalidContactCardError;
+type index_InvalidDidKeyError = InvalidDidKeyError;
+declare const index_InvalidDidKeyError: typeof InvalidDidKeyError;
 type index_InvalidEnvelopeError = InvalidEnvelopeError;
 declare const index_InvalidEnvelopeError: typeof InvalidEnvelopeError;
 type index_KeyPinningError = KeyPinningError;
 declare const index_KeyPinningError: typeof KeyPinningError;
 type index_Keypair = Keypair;
+declare const index_MAX_ENVELOPE_AGE: typeof MAX_ENVELOPE_AGE;
 declare const index_MAX_ENVELOPE_SIZE: typeof MAX_ENVELOPE_SIZE;
 type index_MessageEnvelope = MessageEnvelope;
 type index_MessageType = MessageType;
 declare const index_MessageType: typeof MessageType;
 type index_Seed = Seed;
+type index_SendRefusedError = SendRefusedError;
+declare const index_SendRefusedError: typeof SendRefusedError;
 type index_SignatureError = SignatureError;
 declare const index_SignatureError: typeof SignatureError;
 type index_SignatureVerificationError = SignatureVerificationError;
 declare const index_SignatureVerificationError: typeof SignatureVerificationError;
+type index_SignedObjectError = SignedObjectError;
+declare const index_SignedObjectError: typeof SignedObjectError;
 type index_SigningKey = SigningKey;
 type index_UAMError = UAMError;
 declare const index_UAMError: typeof UAMError;
 declare const index_UAM_VERSION: typeof UAM_VERSION;
 type index_VerifyKey = VerifyKey;
+type index_WebAuthnError = WebAuthnError;
+declare const index_WebAuthnError: typeof WebAuthnError;
+declare const index_approvalChallenge: typeof approvalChallenge;
 declare const index_b64Decode: typeof b64Decode;
 declare const index_b64Encode: typeof b64Encode;
+declare const index_canonical: typeof canonical;
 declare const index_canonicalize: typeof canonicalize;
 declare const index_contactCardFromDict: typeof contactCardFromDict;
 declare const index_contactCardToDict: typeof contactCardToDict;
 declare const index_createContactCard: typeof createContactCard;
 declare const index_createEnvelope: typeof createEnvelope;
+declare const index_credentialDid: typeof credentialDid;
+declare const index_decodeDidKey: typeof decodeDidKey;
 declare const index_decryptPayload: typeof decryptPayload;
 declare const index_decryptPayloadAnonymous: typeof decryptPayloadAnonymous;
 declare const index_deserializeSigningKey: typeof deserializeSigningKey;
 declare const index_deserializeVerifyKey: typeof deserializeVerifyKey;
+declare const index_encodeDidKey: typeof encodeDidKey;
 declare const index_encryptPayload: typeof encryptPayload;
 declare const index_encryptPayloadAnonymous: typeof encryptPayloadAnonymous;
 declare const index_fromWireDict: typeof fromWireDict;
 declare const index_generateKeypair: typeof generateKeypair;
 declare const index_generateNonce: typeof generateNonce;
+declare const index_objectHash: typeof objectHash;
 declare const index_parseAddress: typeof parseAddress;
+declare const index_parseBody: typeof parseBody;
 declare const index_publicKeyFingerprint: typeof publicKeyFingerprint;
 declare const index_serializeSigningKey: typeof serializeSigningKey;
 declare const index_serializeVerifyKey: typeof serializeVerifyKey;
@@ -438,11 +582,13 @@ declare const index_sodiumReady: typeof sodiumReady;
 declare const index_toWireDict: typeof toWireDict;
 declare const index_utcTimestamp: typeof utcTimestamp;
 declare const index_validateEnvelopeSize: typeof validateEnvelopeSize;
+declare const index_verifyAssertion: typeof verifyAssertion;
 declare const index_verifyContactCard: typeof verifyContactCard;
 declare const index_verifyEnvelope: typeof verifyEnvelope;
+declare const index_verifyRegistration: typeof verifyRegistration;
 declare const index_verifySignature: typeof verifySignature;
 declare namespace index {
-  export { type index_Address as Address, type index_ContactCard as ContactCard, index_DecryptionError as DecryptionError, index_EncryptionError as EncryptionError, index_EnvelopeTooLargeError as EnvelopeTooLargeError, index_InvalidAddressError as InvalidAddressError, index_InvalidContactCardError as InvalidContactCardError, index_InvalidEnvelopeError as InvalidEnvelopeError, index_KeyPinningError as KeyPinningError, type index_Keypair as Keypair, index_MAX_ENVELOPE_SIZE as MAX_ENVELOPE_SIZE, type index_MessageEnvelope as MessageEnvelope, index_MessageType as MessageType, type index_Seed as Seed, index_SignatureError as SignatureError, index_SignatureVerificationError as SignatureVerificationError, type index_SigningKey as SigningKey, index_UAMError as UAMError, index_UAM_VERSION as UAM_VERSION, type index_VerifyKey as VerifyKey, index_b64Decode as b64Decode, index_b64Encode as b64Encode, index_canonicalize as canonicalize, index_contactCardFromDict as contactCardFromDict, index_contactCardToDict as contactCardToDict, index_createContactCard as createContactCard, index_createEnvelope as createEnvelope, index_decryptPayload as decryptPayload, index_decryptPayloadAnonymous as decryptPayloadAnonymous, index_deserializeSigningKey as deserializeSigningKey, index_deserializeVerifyKey as deserializeVerifyKey, index_encryptPayload as encryptPayload, index_encryptPayloadAnonymous as encryptPayloadAnonymous, index_fromWireDict as fromWireDict, index_generateKeypair as generateKeypair, index_generateNonce as generateNonce, index_parseAddress as parseAddress, index_publicKeyFingerprint as publicKeyFingerprint, index_serializeSigningKey as serializeSigningKey, index_serializeVerifyKey as serializeVerifyKey, index_signMessage as signMessage, index_sodiumReady as sodiumReady, index_toWireDict as toWireDict, index_utcTimestamp as utcTimestamp, index_validateEnvelopeSize as validateEnvelopeSize, index_verifyContactCard as verifyContactCard, index_verifyEnvelope as verifyEnvelope, index_verifySignature as verifySignature };
+  export { type index_Address as Address, type index_ContactCard as ContactCard, index_DecryptionError as DecryptionError, type index_DidKeyKind as DidKeyKind, index_EncryptionError as EncryptionError, index_EnvelopeTooLargeError as EnvelopeTooLargeError, index_InvalidAddressError as InvalidAddressError, index_InvalidContactCardError as InvalidContactCardError, index_InvalidDidKeyError as InvalidDidKeyError, index_InvalidEnvelopeError as InvalidEnvelopeError, index_KeyPinningError as KeyPinningError, type index_Keypair as Keypair, index_MAX_ENVELOPE_AGE as MAX_ENVELOPE_AGE, index_MAX_ENVELOPE_SIZE as MAX_ENVELOPE_SIZE, type index_MessageEnvelope as MessageEnvelope, index_MessageType as MessageType, type Credential as PasskeyCredential, type index_Seed as Seed, index_SendRefusedError as SendRefusedError, index_SignatureError as SignatureError, index_SignatureVerificationError as SignatureVerificationError, type Body as SignedBody, index_SignedObjectError as SignedObjectError, type index_SigningKey as SigningKey, index_UAMError as UAMError, index_UAM_VERSION as UAM_VERSION, type index_VerifyKey as VerifyKey, index_WebAuthnError as WebAuthnError, index_approvalChallenge as approvalChallenge, index_b64Decode as b64Decode, index_b64Encode as b64Encode, index_canonical as canonical, index_canonicalize as canonicalize, index_contactCardFromDict as contactCardFromDict, index_contactCardToDict as contactCardToDict, index_createContactCard as createContactCard, index_createEnvelope as createEnvelope, index_credentialDid as credentialDid, index_decodeDidKey as decodeDidKey, index_decryptPayload as decryptPayload, index_decryptPayloadAnonymous as decryptPayloadAnonymous, index_deserializeSigningKey as deserializeSigningKey, index_deserializeVerifyKey as deserializeVerifyKey, index_encodeDidKey as encodeDidKey, index_encryptPayload as encryptPayload, index_encryptPayloadAnonymous as encryptPayloadAnonymous, index_fromWireDict as fromWireDict, index_generateKeypair as generateKeypair, index_generateNonce as generateNonce, index_objectHash as objectHash, index_parseAddress as parseAddress, index_parseBody as parseBody, index_publicKeyFingerprint as publicKeyFingerprint, index_serializeSigningKey as serializeSigningKey, index_serializeVerifyKey as serializeVerifyKey, index_signMessage as signMessage, index_sodiumReady as sodiumReady, index_toWireDict as toWireDict, index_utcTimestamp as utcTimestamp, index_validateEnvelopeSize as validateEnvelopeSize, validate as validateSignedObject, index_verifyAssertion as verifyAssertion, index_verifyContactCard as verifyContactCard, index_verifyEnvelope as verifyEnvelope, index_verifyRegistration as verifyRegistration, index_verifySignature as verifySignature };
 }
 
 /**
@@ -474,13 +620,31 @@ declare class KeyManager {
      * Store the relay token alongside the keypair.
      */
     saveToken(name: string, token: string): void;
+    /**
+     * Store the address `relayUrl` gave this agent.
+     */
+    saveAddress(name: string, address: string, relayUrl: string): void;
+    /**
+     * 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: string, relayUrl: string): string | null;
     /**
      * Load a previously saved token, or return null.
      *
      * Checks UAM_TOKEN env var first, then file-based storage,
-     * then legacy .api_key files for backward compatibility.
+     * then legacy .api_key files for backward compatibility. With `relayUrl`,
+     * a saved token that belongs to another relay counts as none, so it is
+     * only offered to the relay that issued it.
+     */
+    loadToken(name: string, relayUrl?: string): string | null;
+    /**
+     * True if the saved address says this agent's files are another relay's.
+     * A missing or damaged file says nothing.
      */
-    loadToken(name: string): string | null;
+    private _savedForAnotherRelay;
     /** Set file permissions to 0o600 (owner read/write only). */
     private _setPermissions;
     /** Warn if key file permissions are too permissive. */
@@ -512,6 +676,30 @@ interface ReceivedMessage {
     readonly mediaType?: string;
     readonly verified: boolean;
 }
+/** What a relay can say it did with a sent message (as the Python SDK). */
+declare const SEND_STATUSES: readonly ["delivered", "stored", "relayed", "queued", "duplicate", "dropped", "pending", "accepted", "unknown"];
+type SendStatus = (typeof SEND_STATUSES)[number];
+/**
+ * What Agent.send() returns.
+ *
+ * `status` is one of SEND_STATUSES: "pending" means the recipient only
+ * takes messages from approved contacts and the relay kept nothing.
+ * `delivered` is true only when the relay says the recipient has it.
+ */
+interface SendResult {
+    readonly messageId: string;
+    readonly status: SendStatus;
+    readonly delivered: boolean;
+}
+/**
+ * True when a relay's features include `name` at `version` or later.
+ *
+ * "name" is version 1; "name:N" means version N or later.
+ */
+declare function supports(features: Iterable<string>, name: string, version?: number): boolean;
+/** What to tell whoever sent a message the relay answered "pending". */
+declare const PENDING_NOTE: string;
+declare function pendingNote(to: string): string;
 
 /**
  * SQLite-backed local contact storage (HAND-03).
@@ -583,6 +771,14 @@ declare class ContactBook {
     getRelayUrls(address: string): string[] | 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: string, publicKey: string, options?: {
         displayName?: string | null;
@@ -590,6 +786,7 @@ declare class ContactBook {
         trustSource?: string | null;
         relay?: string | null;
         relays?: string[] | null;
+        force?: boolean;
     }): void;
     /**
      * Return all contacts sorted by last_seen DESC.
@@ -666,7 +863,7 @@ interface AgentLike {
         readonly signingKey: Uint8Array;
     };
     readonly _transport: {
-        send(envelope: Record<string, unknown>): Promise<void>;
+        send(envelope: Record<string, unknown>): Promise<unknown>;
     } | null;
 }
 declare class HandshakeManager {
@@ -694,6 +891,16 @@ declare class HandshakeManager {
     private _handleRequest;
     /**
      * 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).
      */
     private _handleAccept;
     /**
@@ -718,8 +925,13 @@ declare abstract class TransportBase {
     abstract connect(): Promise<void>;
     /** Close the connection. */
     abstract disconnect(): Promise<void>;
-    /** Send a message envelope to the relay. */
-    abstract send(envelope: Record<string, unknown>): Promise<void>;
+    /**
+     * Send a message envelope to the relay.
+     *
+     * Resolves with the relay's answer (`{status, ...}`), or null when none
+     * came in time: the message may still have arrived.
+     */
+    abstract send(envelope: Record<string, unknown>): Promise<Record<string, unknown> | null>;
     /** Retrieve pending messages from the relay. */
     abstract receive(limit?: number): Promise<Record<string, unknown>[]>;
     /**
@@ -731,6 +943,55 @@ declare abstract class TransportBase {
     abstract listen(callback: (msg: Record<string, unknown>) => Promise<void>): Promise<void>;
 }
 
+/**
+ * Inbound (from address, message id) pairs kept in a SQLite file.
+ *
+ * Opens itself on first use, so an Agent driven without connect() still has
+ * replay protection. Safe to share between processes: the insert is the
+ * check (INSERT OR IGNORE), in WAL mode.
+ */
+declare class PersistentReplayCache {
+    readonly capacity: number;
+    private readonly _path;
+    private readonly _now;
+    private _db;
+    private _opening;
+    private _count;
+    private _lastPurge;
+    private _createdAt;
+    private readonly _overflow;
+    /**
+     * @param path - The SQLite file
+     * @param options.now - The clock, in ms since the epoch
+     */
+    constructor(path: string, options?: {
+        capacity?: number;
+        now?: () => number;
+    });
+    /** Open the file now, rather than on first use. */
+    open(): Promise<void>;
+    /**
+     * 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.
+     */
+    seenOrRecord(fromAddress: string, messageId: string, signedAt: number): Promise<boolean>;
+    /** When this cache file was first created, in ms since the epoch. */
+    createdAt(): Promise<number>;
+    /** True if an envelope signed at `signedAt` (ms) predates this cache. */
+    signedBeforeCache(signedAt: number): Promise<boolean>;
+    /** Number of ids currently held on disk. */
+    count(): Promise<number>;
+    /** Close the file; the next call opens it again. */
+    close(): Promise<void>;
+    private _open;
+    private _connect;
+    private _purge;
+    private _countRows;
+}
+
 /**
  * Agent class -- the primary SDK interface (SDK-01).
  *
@@ -756,6 +1017,23 @@ declare class Agent {
     readonly _contactBook: ContactBook;
     /** @internal */
     readonly _handshake: HandshakeManager;
+    /**
+     * @internal Wall clock in ms since the epoch, used by the inbound
+     * freshness/expiry checks and the replay cache. Replaceable in tests.
+     */
+    _clock: () => number;
+    /**
+     * @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.
+     */
+    readonly _replayCache: PersistentReplayCache;
+    /** Whether our relay has said it writes relay_meta. */
+    private _relayStamps;
+    /** Until when, by _monotonic, to take the relay's last no as still true. */
+    private _relayNoUntil;
+    /** @internal Monotonic clock in ms. Replaceable in tests. */
+    _monotonic: () => number;
     /**
      * Create an Agent. No I/O happens here -- call connect() to initialize.
      */
@@ -791,17 +1069,25 @@ declare class Agent {
      */
     close(): Promise<void>;
     /**
-     * Send an encrypted, signed message. Returns the message_id.
+     * Send an encrypted, signed message.
+     *
+     * Returns the message id with what the relay did with it: `status`
+     * "pending" means the recipient only takes approved contacts, and the
+     * message was not kept (don't resend it). `delivered` is true only when
+     * the relay says the recipient has it.
      */
     send(toAddress: string, message: string, options?: {
         threadId?: string;
         attachments?: Array<Record<string, unknown>>;
-    }): Promise<string>;
+    }): Promise<SendResult>;
     /**
      * Retrieve, decrypt, and verify pending messages.
      *
      * Returns a list of ReceivedMessage data objects.
-     * Silently drops messages with invalid signatures or decryption errors.
+     * Drops messages with invalid signatures or decryption errors. A message
+     * that fails processing for any other reason (malformed envelope, bad
+     * handshake payload, ...) is logged and dropped; it never aborts the
+     * rest of the batch.
      */
     inbox(limit?: number): Promise<ReceivedMessage[]>;
     /** List pending handshake requests. */
@@ -857,6 +1143,10 @@ declare class Agent {
     /**
      * 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.
@@ -869,6 +1159,26 @@ declare class Agent {
      * Returns null for invalid messages or handshake protocol messages.
      */
     private _processInbound;
+    /**
+     * 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.
+     */
+    private _passesInboundChecks;
+    /** True if a message too old to be live is stored mail, not a replay. */
+    private _wasStored;
+    /**
+     * 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.
+     */
+    private _relayStampsMail;
+    /** The relay's features; a body that doesn't list any is an empty list. */
+    private _fetchRelayFeatures;
     /**
      * Sweep expired pending handshakes and send receipt.failed (HAND-03).
      */
@@ -883,10 +1193,80 @@ declare class Agent {
     /**
      * Register with the relay server.
      *
-     * Calls POST /api/v1/register with agent name and public key.
-     * Stores the returned API key on disk.
+     * Calls POST /api/v1/register with agent name and public key. If the
+     * address exists (409), repeats it with a proof that this agent holds the
+     * key. Stores the returned API key on disk.
      */
     private _registerWithRelay;
+    /** This agent's address on the relay, for signing a proof. */
+    private _addressOnRelay;
+    /**
+     * 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.
+     */
+    private _relayMayUse;
+    private _postRegistration;
+    /**
+     * Sign a statement that this agent holds the key for `address`.
+     *
+     * The signed string must stay byte-identical to the Python SDK's.
+     */
+    private _registrationProof;
+    private _ownershipNotProven;
+    /** Remember `address` for this relay, if the key folder allows it. */
+    private _saveAddress;
+    /** Saving is best effort: a key folder we can't write doesn't stop us. */
+    private _tryToSave;
+    /** Take `address` as ours; its domain is this relay's real domain. */
+    private _useAddress;
+    /**
+     * 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.
+     */
+    private _storedAddress;
+    /** Ask the relay for its domain; null if it cannot say. */
+    private _fetchRelayDomain;
 }
 
-export { Agent, type ReceivedMessage, index as protocol };
+/**
+ * Receiver-side webhook signature verification (HOOK-03).
+ *
+ * Small utility for webhook receivers to verify that incoming webhook
+ * payloads were signed by the UAM relay.  Uses HMAC-SHA256 with the
+ * agent's webhook secret, which the relay returns when the webhook is set
+ * (PUT /api/v1/agents/{address}/webhook).  Setting the same URL again
+ * returns it again.
+ *
+ * Matches Python webhook_verify.py API surface.
+ *
+ * Usage:
+ *
+ *     import { verifyWebhookSignature } from "@youam/sdk";
+ *
+ *     const payload = Buffer.from(requestBody);
+ *     const signature = request.headers["x-uam-signature"];
+ *     const secret = "your-webhook-secret";
+ *
+ *     if (verifyWebhookSignature(payload, signature, secret)) {
+ *       // payload is authentic
+ *     }
+ */
+/**
+ * Verify an HMAC-SHA256 webhook signature.
+ *
+ * @param payload - Raw request body bytes
+ * @param signatureHeader - "sha256=<hex>" format (X-UAM-Signature header)
+ * @param secret - The agent's webhook secret
+ * @returns `true` if valid, `false` otherwise.
+ *
+ * Uses `crypto.timingSafeEqual()` for constant-time comparison
+ * to prevent timing attacks.
+ */
+declare function verifyWebhookSignature(payload: Buffer | Uint8Array, signatureHeader: string, secret: string): boolean;
+
+export { Agent, ContactBook, PENDING_NOTE, type ReceivedMessage, SEND_STATUSES, type SendResult, type SendStatus, pendingNote, index as protocol, supports, verifyWebhookSignature };