@youam/sdk 0.2.0 → 0.2.1

package/dist/index.d.cts

@@ -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",
@@ -399,6 +401,7 @@ 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;
@@ -442,7 +445,7 @@ declare const index_verifyContactCard: typeof verifyContactCard;
 declare const index_verifyEnvelope: typeof verifyEnvelope;
 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, 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_AGE as MAX_ENVELOPE_AGE, 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 };
 }
 
 /**
@@ -474,13 +477,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. */
@@ -583,6 +604,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 +619,7 @@ declare class ContactBook {
         trustSource?: string | null;
         relay?: string | null;
         relays?: string[] | null;
+        force?: boolean;
     }): void;
     /**
      * Return all contacts sorted by last_seen DESC.
@@ -694,6 +724,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;
     /**
@@ -731,6 +771,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 +845,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.
      */
@@ -801,7 +907,10 @@ declare class Agent {
      * 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 +966,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 +982,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 +1016,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, type ReceivedMessage, index as protocol, verifyWebhookSignature };

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",
@@ -399,6 +401,7 @@ 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;
@@ -442,7 +445,7 @@ declare const index_verifyContactCard: typeof verifyContactCard;
 declare const index_verifyEnvelope: typeof verifyEnvelope;
 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, 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_AGE as MAX_ENVELOPE_AGE, 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 };
 }
 
 /**
@@ -474,13 +477,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. */
@@ -583,6 +604,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 +619,7 @@ declare class ContactBook {
         trustSource?: string | null;
         relay?: string | null;
         relays?: string[] | null;
+        force?: boolean;
     }): void;
     /**
      * Return all contacts sorted by last_seen DESC.
@@ -694,6 +724,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;
     /**
@@ -731,6 +771,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 +845,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.
      */
@@ -801,7 +907,10 @@ declare class Agent {
      * 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 +966,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 +982,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 +1016,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, type ReceivedMessage, index as protocol, verifyWebhookSignature };