@youam/sdk 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,1095 @@
+declare class SDKConfig {
+    readonly name: string;
+    readonly relayUrl: string;
+    readonly relayWsUrl: string;
+    readonly keyDir: string;
+    readonly dataDir: string;
+    readonly displayName: string;
+    readonly transportType: string;
+    readonly trustPolicy: 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;
+        relayWsUrl?: string | null;
+        keyDir?: string | null;
+        dataDir?: string | null;
+        displayName?: string | null;
+        transportType?: string;
+        trustPolicy?: string;
+        relayDomain?: string;
+    });
+}
+
+/**
+ * Core types, constants, and utility functions for UAM protocol.
+ */
+/** Protocol version. */
+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",
+    HANDSHAKE_REQUEST = "handshake.request",
+    HANDSHAKE_ACCEPT = "handshake.accept",
+    HANDSHAKE_DENY = "handshake.deny",
+    RECEIPT_DELIVERED = "receipt.delivered",
+    RECEIPT_READ = "receipt.read",
+    RECEIPT_FAILED = "receipt.failed",
+    SESSION_REQUEST = "session.request",
+    SESSION_ACCEPT = "session.accept",
+    SESSION_DECLINE = "session.decline",
+    SESSION_END = "session.end"
+}
+/**
+ * URL-safe base64 encode, stripping padding.
+ */
+declare function b64Encode(data: Uint8Array): string;
+/**
+ * URL-safe base64 decode, tolerating missing padding.
+ */
+declare function b64Decode(s: string): Uint8Array;
+/**
+ * Return a canonical UTC timestamp: YYYY-MM-DDTHH:MM:SS.mmmZ
+ */
+declare function utcTimestamp(): string;
+
+/**
+ * UAM exception hierarchy.
+ *
+ * All protocol-specific errors inherit from UAMError.
+ */
+/** Base error for all UAM protocol errors. */
+declare class UAMError extends Error {
+    constructor(message?: string);
+}
+/** Raised when an address string fails validation. */
+declare class InvalidAddressError extends UAMError {
+    constructor(message?: string);
+}
+/** Raised when an envelope fails schema validation. */
+declare class InvalidEnvelopeError extends UAMError {
+    constructor(message?: string);
+}
+/** Raised when an envelope exceeds the maximum allowed size. */
+declare class EnvelopeTooLargeError extends InvalidEnvelopeError {
+    constructor(message?: string);
+}
+/** Raised on signing failures. */
+declare class SignatureError extends UAMError {
+    constructor(message?: string);
+}
+/** Raised when a cryptographic signature cannot be verified. */
+declare class SignatureVerificationError extends SignatureError {
+    constructor(message?: string);
+}
+/** Raised on encryption failures. */
+declare class EncryptionError extends UAMError {
+    constructor(message?: string);
+}
+/** Raised on decryption failures. */
+declare class DecryptionError extends EncryptionError {
+    constructor(message?: string);
+}
+/** Raised when a contact card fails validation. */
+declare class InvalidContactCardError extends UAMError {
+    constructor(message?: string);
+}
+/** Raised when a pinned contact's public key doesn't match the resolved key. */
+declare class KeyPinningError extends UAMError {
+    constructor(message?: string);
+}
+
+/**
+ * UAM address parsing and validation.
+ *
+ * A UAM address has the form `agent::domain` (e.g. `alice::youam.network`).
+ */
+/**
+ * A parsed UAM address (always lowercase).
+ */
+interface Address {
+    readonly agent: string;
+    readonly domain: string;
+    readonly full: string;
+}
+/**
+ * Parse and validate a UAM address string.
+ *
+ * Strips whitespace, lowercases, and validates format.
+ * Enforces max lengths: agent <= 64 chars, full address <= 128 chars.
+ *
+ * @throws {InvalidAddressError} If `raw` is not a valid `agent::domain` address.
+ */
+declare function parseAddress(raw: string): Address;
+
+/**
+ * Cryptographic primitives for UAM protocol.
+ *
+ * Wraps libsodium-wrappers for Ed25519 signing, Curve25519 key exchange,
+ * NaCl Box (authenticated encryption), and NaCl SealedBox (anonymous encryption).
+ *
+ * This module never hand-rolls crypto -- every operation delegates to libsodium.
+ */
+/**
+ * Promise that resolves when libsodium is ready.
+ * Callers must await this before first use of any crypto function.
+ */
+declare const sodiumReady: Promise<void>;
+/** 64-byte Ed25519 secret key (seed + public). */
+type SigningKey = Uint8Array;
+/** 32-byte Ed25519 public key. */
+type VerifyKey = Uint8Array;
+/** 32-byte seed. */
+type Seed = Uint8Array;
+interface Keypair {
+    signingKey: Uint8Array;
+    verifyKey: Uint8Array;
+    seed: Uint8Array;
+}
+/**
+ * Generate an Ed25519 keypair.
+ */
+declare function generateKeypair(): Keypair;
+/**
+ * Serialize a signing key to URL-safe base64 (32-byte seed).
+ *
+ * Matches Python: PyNaCl's SigningKey.encode() returns the 32-byte seed.
+ */
+declare function serializeSigningKey(seed: Uint8Array): string;
+/**
+ * Restore a signing key from its base64-encoded seed.
+ */
+declare function deserializeSigningKey(s: string): Keypair;
+/**
+ * Serialize a verify (public) key to URL-safe base64.
+ */
+declare function serializeVerifyKey(key: Uint8Array): string;
+/**
+ * Restore a verify key from its base64 encoding.
+ */
+declare function deserializeVerifyKey(s: string): Uint8Array;
+/**
+ * Return the SHA-256 hex digest of the verify key bytes.
+ *
+ * This 64-character string serves as the agent's identity fingerprint.
+ */
+declare function publicKeyFingerprint(verifyKey: Uint8Array): string;
+/**
+ * Produce deterministic JSON bytes for signing.
+ *
+ * - Excludes the "signature" key.
+ * - Excludes keys whose value is null or undefined.
+ * - Sorts keys, uses compact separators, ensures ASCII encoding.
+ */
+declare function canonicalize(data: Record<string, unknown>): Uint8Array;
+/**
+ * Sign data with the Ed25519 signing key.
+ *
+ * @returns The 64-byte signature as a URL-safe base64 string.
+ */
+declare function signMessage(data: Uint8Array, signingKey: Uint8Array): string;
+/**
+ * Verify an Ed25519 signature.
+ *
+ * @throws {SignatureVerificationError} If the signature is invalid.
+ */
+declare function verifySignature(data: Uint8Array, signatureB64: string, verifyKey: Uint8Array): void;
+/**
+ * Generate 24 cryptographically random bytes, returned as base64.
+ */
+declare function generateNonce(): string;
+/**
+ * Encrypt plaintext using NaCl Box (authenticated encryption).
+ *
+ * Both parties are known; the sender signs implicitly via key exchange.
+ * Format: nonce (24 bytes) || ciphertext, matching PyNaCl Box.encrypt() output.
+ *
+ * @returns Base64-encoded ciphertext (nonce prepended).
+ * @throws {EncryptionError} On any libsodium error.
+ */
+declare function encryptPayload(plaintext: Uint8Array, senderSigningKey: Uint8Array, recipientVerifyKey: Uint8Array): string;
+/**
+ * Decrypt NaCl Box ciphertext.
+ *
+ * @returns The original plaintext bytes.
+ * @throws {DecryptionError} On any libsodium error (wrong keys, tampered data).
+ */
+declare function decryptPayload(ciphertextB64: string, recipientSigningKey: Uint8Array, senderVerifyKey: Uint8Array): Uint8Array;
+/**
+ * Encrypt plaintext using NaCl SealedBox (anonymous sender).
+ *
+ * Only the recipient's public key is required; no sender authentication.
+ *
+ * @returns Base64-encoded ciphertext.
+ */
+declare function encryptPayloadAnonymous(plaintext: Uint8Array, recipientVerifyKey: Uint8Array): string;
+/**
+ * Decrypt NaCl SealedBox ciphertext.
+ *
+ * @returns The original plaintext bytes.
+ * @throws {DecryptionError} On any libsodium error.
+ */
+declare function decryptPayloadAnonymous(ciphertextB64: string, recipientSigningKey: Uint8Array): Uint8Array;
+
+/**
+ * UAM message envelope -- creation, signing, verification, wire format.
+ *
+ * An envelope wraps every UAM message with cryptographic signatures and
+ * encrypted payloads, using fromAddress/toAddress naming internally
+ * ("from"/"to" on the wire).
+ */
+
+/**
+ * A signed, encrypted UAM message envelope.
+ */
+interface MessageEnvelope {
+    readonly uamVersion: string;
+    readonly messageId: string;
+    readonly fromAddress: string;
+    readonly toAddress: string;
+    readonly timestamp: string;
+    readonly type: string;
+    readonly nonce: string;
+    readonly payload: string;
+    readonly signature: string;
+    readonly threadId?: string;
+    readonly replyTo?: string;
+    readonly expires?: string;
+    readonly mediaType?: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly attachments?: Array<Record<string, unknown>>;
+}
+/**
+ * Convert an envelope to a wire-format dict.
+ *
+ * Maps fromAddress -> "from" and toAddress -> "to".
+ * Excludes undefined-valued optional fields.
+ */
+declare function toWireDict(envelope: MessageEnvelope): Record<string, unknown>;
+/**
+ * Restore an envelope from a wire-format dict.
+ *
+ * @throws {InvalidEnvelopeError} If any required field is missing.
+ */
+declare function fromWireDict(d: Record<string, unknown>): MessageEnvelope;
+/**
+ * Check that the serialized envelope does not exceed MAX_ENVELOPE_SIZE.
+ *
+ * @throws {EnvelopeTooLargeError} If the wire JSON exceeds 64 KB.
+ */
+declare function validateEnvelopeSize(envelope: MessageEnvelope): void;
+/**
+ * Create a signed, encrypted message envelope.
+ *
+ * @throws {InvalidAddressError} If either address is invalid.
+ * @throws {EnvelopeTooLargeError} If the serialized envelope exceeds 64 KB.
+ */
+declare function createEnvelope(fromAddress: string, toAddress: string, messageType: MessageType | string, payloadPlaintext: Uint8Array, signingKey: Uint8Array, recipientVerifyKey: Uint8Array, options?: {
+    threadId?: string;
+    replyTo?: string;
+    expires?: string;
+    mediaType?: string;
+    metadata?: Record<string, unknown>;
+    attachments?: Array<Record<string, unknown>>;
+}): Promise<MessageEnvelope>;
+/**
+ * Verify the cryptographic signature on an envelope.
+ *
+ * @throws {SignatureVerificationError} If the signature is invalid.
+ */
+declare function verifyEnvelope(envelope: MessageEnvelope, senderVerifyKey: Uint8Array): void;
+
+/**
+ * UAM contact cards -- self-signed agent identity documents.
+ *
+ * A contact card advertises an agent's address, public key, relay endpoint,
+ * and optional metadata. The card is signed by the agent's own signing key
+ * so that any recipient can verify authenticity using the embedded public key.
+ */
+/**
+ * A self-signed agent identity card.
+ */
+interface ContactCard {
+    readonly version: string;
+    readonly address: string;
+    readonly displayName: string;
+    readonly description?: string;
+    readonly system?: string;
+    readonly connectionEndpoint?: string;
+    readonly relay: string;
+    readonly publicKey: string;
+    readonly signature: string;
+    readonly verifiedDomain?: string;
+    readonly payloadFormats?: string[];
+    readonly fingerprint?: string;
+    /** CARD-04: Multi-relay support. Outside signature scope. */
+    readonly relays?: string[];
+}
+/**
+ * Serialize a contact card to a plain dict.
+ *
+ * Uses snake_case names on the wire, excludes undefined-valued optional fields.
+ */
+declare function contactCardToDict(card: ContactCard): Record<string, unknown>;
+/**
+ * Deserialize a contact card from a dict.
+ *
+ * When verify is true (the default), the card's signature is checked
+ * immediately after deserialization.
+ *
+ * @throws {InvalidContactCardError} If required fields are missing.
+ * @throws {SignatureVerificationError} If verify is true and the signature is invalid.
+ */
+declare function contactCardFromDict(d: Record<string, unknown>, options?: {
+    verify?: boolean;
+}): ContactCard;
+/**
+ * Create a self-signed contact card.
+ *
+ * payloadFormats defaults to ["text/plain", "text/markdown"] when not specified.
+ * The fingerprint is always auto-computed as the SHA-256 hex digest of the
+ * Ed25519 public key bytes.
+ *
+ * @throws {InvalidAddressError} If address is not valid.
+ */
+declare function createContactCard(address: string, displayName: string, relay: string, signingKey: Uint8Array, options?: {
+    description?: string;
+    system?: string;
+    connectionEndpoint?: string;
+    verifiedDomain?: string;
+    payloadFormats?: string[];
+    relays?: string[];
+}): Promise<ContactCard>;
+/**
+ * Verify a contact card's signature using its embedded public key.
+ *
+ * @throws {InvalidContactCardError} If the address is invalid.
+ * @throws {SignatureVerificationError} If the signature is invalid.
+ */
+declare function verifyContactCard(card: ContactCard): void;
+
+/**
+ * UAM Protocol -- Universal Agent Messaging protocol library.
+ *
+ * Public API re-exports for the protocol layer.
+ */
+
+type index_Address = Address;
+type index_ContactCard = ContactCard;
+type index_DecryptionError = DecryptionError;
+declare const index_DecryptionError: typeof DecryptionError;
+type index_EncryptionError = EncryptionError;
+declare const index_EncryptionError: typeof EncryptionError;
+type index_EnvelopeTooLargeError = EnvelopeTooLargeError;
+declare const index_EnvelopeTooLargeError: typeof EnvelopeTooLargeError;
+type index_InvalidAddressError = InvalidAddressError;
+declare const index_InvalidAddressError: typeof InvalidAddressError;
+type index_InvalidContactCardError = InvalidContactCardError;
+declare const index_InvalidContactCardError: typeof InvalidContactCardError;
+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_SignatureError = SignatureError;
+declare const index_SignatureError: typeof SignatureError;
+type index_SignatureVerificationError = SignatureVerificationError;
+declare const index_SignatureVerificationError: typeof SignatureVerificationError;
+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;
+declare const index_b64Decode: typeof b64Decode;
+declare const index_b64Encode: typeof b64Encode;
+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_decryptPayload: typeof decryptPayload;
+declare const index_decryptPayloadAnonymous: typeof decryptPayloadAnonymous;
+declare const index_deserializeSigningKey: typeof deserializeSigningKey;
+declare const index_deserializeVerifyKey: typeof deserializeVerifyKey;
+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_parseAddress: typeof parseAddress;
+declare const index_publicKeyFingerprint: typeof publicKeyFingerprint;
+declare const index_serializeSigningKey: typeof serializeSigningKey;
+declare const index_serializeVerifyKey: typeof serializeVerifyKey;
+declare const index_signMessage: typeof signMessage;
+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_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_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 };
+}
+
+/**
+ * Ed25519 key generation, storage, loading, and token persistence.
+ *
+ * Matches Python key_manager.py: stores 32-byte seed (not 64-byte secret key),
+ * uses same file format so keys are cross-language compatible.
+ */
+
+declare class KeyManager {
+    private _keyDir;
+    private _keypair;
+    constructor(keyDir?: string | null);
+    /** The 64-byte Ed25519 signing key. Throws if not loaded. */
+    get signingKey(): SigningKey;
+    /** The 32-byte Ed25519 verify (public) key. Throws if not loaded. */
+    get verifyKey(): VerifyKey;
+    /** The 32-byte seed. Throws if not loaded. */
+    get seed(): 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: string): void;
+    /**
+     * 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. 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.
+     */
+    private _savedForAnotherRelay;
+    /** Set file permissions to 0o600 (owner read/write only). */
+    private _setPermissions;
+    /** Warn if key file permissions are too permissive. */
+    private _checkPermissions;
+}
+
+/**
+ * ReceivedMessage -- frozen data object for inbound messages.
+ *
+ * Matches Python message.py: a readonly interface for decrypted messages.
+ * The toString() omission is deliberate prompt-injection isolation (SDK-10).
+ */
+/**
+ * A decrypted, verified inbound message.
+ *
+ * This is a DATA OBJECT. Framework integrations must explicitly
+ * extract .content to use in prompts. The SDK never concatenates
+ * message content into LLM context automatically.
+ */
+interface ReceivedMessage {
+    readonly messageId: string;
+    readonly fromAddress: string;
+    readonly toAddress: string;
+    readonly content: string;
+    readonly timestamp: string;
+    readonly type: string;
+    readonly threadId?: string;
+    readonly replyTo?: string;
+    readonly mediaType?: string;
+    readonly verified: boolean;
+}
+
+/**
+ * SQLite-backed local contact storage (HAND-03).
+ *
+ * Stores known contacts with their public keys and trust state.
+ * Provides fast in-memory caches for isKnown() and isBlocked() checks.
+ *
+ * Uses better-sqlite3 for synchronous SQLite (simpler than Python's aiosqlite).
+ */
+/**
+ * A row returned from listContacts().
+ */
+interface ContactRow {
+    address: string;
+    displayName: string | null;
+    trustState: string;
+    firstSeen: string;
+    lastSeen: string;
+}
+/**
+ * A pending handshake entry.
+ */
+interface PendingEntry {
+    address: string;
+    contactCard: string;
+    receivedAt: string;
+}
+/**
+ * A blocked pattern entry.
+ */
+interface BlockedEntry {
+    pattern: string;
+    blockedAt: string;
+}
+declare class ContactBook {
+    private _dbPath;
+    private _db;
+    private _knownAddresses;
+    private _blockedExact;
+    private _blockedDomains;
+    constructor(dataDir: string);
+    /**
+     * Open the database, create tables, run migrations, load caches.
+     */
+    open(): void;
+    /**
+     * Run schema migrations using PRAGMA user_version.
+     */
+    private _migrate;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+    /**
+     * Check if an address is in the contact book (in-memory, no I/O).
+     */
+    isKnown(address: string): boolean;
+    /**
+     * Check if an address matches any blocked pattern (O(1) set lookup).
+     */
+    isBlocked(address: string): boolean;
+    /**
+     * Look up the public key for a known contact.
+     */
+    getPublicKey(address: string): string | null;
+    /**
+     * Return the relay URLs for a known contact (CARD-04).
+     */
+    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;
+        trustState?: string;
+        trustSource?: string | null;
+        relay?: string | null;
+        relays?: string[] | null;
+        force?: boolean;
+    }): void;
+    /**
+     * Return all contacts sorted by last_seen DESC.
+     */
+    listContacts(): ContactRow[];
+    /**
+     * Store a pending handshake request.
+     */
+    addPending(address: string, contactCardJson: string): void;
+    /**
+     * Retrieve all pending handshake requests.
+     */
+    getPending(): PendingEntry[];
+    /**
+     * Remove a pending handshake request.
+     */
+    removePending(address: string): void;
+    /**
+     * Return pending handshakes older than N days.
+     */
+    getExpiredPending(days?: number): PendingEntry[];
+    /**
+     * Return the trust_state for an address, or null if unknown.
+     */
+    getTrustState(address: string): string | null;
+    /**
+     * Set the pinned_at timestamp and trust_state='pinned' for a contact (TOFU).
+     */
+    setPinnedAt(address: string): void;
+    /**
+     * Remove a contact by address. Returns true if a contact was deleted.
+     */
+    removeContact(address: string): boolean;
+    /**
+     * Return true if the address has trust_state 'trusted', 'verified', or 'pinned'.
+     *
+     * Convenience helper for inbound message filtering (CARD-05, TOFU-02).
+     */
+    isTrustedOrVerified(address: string): boolean;
+    /**
+     * Block an address or domain pattern (e.g., '*::evil.com').
+     */
+    addBlock(pattern: string): void;
+    /**
+     * Remove a block pattern.
+     */
+    removeBlock(pattern: string): void;
+    /**
+     * Return all blocked patterns with their timestamps.
+     */
+    listBlocked(): BlockedEntry[];
+    private _cacheBlockPattern;
+    private _uncacheBlockPattern;
+}
+
+/**
+ * First-contact handshake flow manager (HAND-01 through HAND-04).
+ *
+ * Handles the three-phase handshake:
+ *   1. HANDSHAKE_REQUEST: sender sends contact card (encrypted with SealedBox)
+ *   2. HANDSHAKE_ACCEPT: recipient stores contact and sends accept back
+ *   3. HANDSHAKE_DENY: recipient rejects the handshake
+ *
+ * The HandshakeManager works with the ContactBook to persist trust decisions.
+ */
+
+interface AgentLike {
+    readonly address: string;
+    readonly _config: {
+        readonly displayName: string;
+        readonly relayWsUrl: string;
+    };
+    readonly _keyManager: {
+        readonly signingKey: Uint8Array;
+    };
+    readonly _transport: {
+        send(envelope: Record<string, unknown>): Promise<void>;
+    } | null;
+}
+declare class HandshakeManager {
+    private _contactBook;
+    readonly _trustPolicy: string;
+    constructor(contactBook: ContactBook, trustPolicy: string);
+    /**
+     * 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.
+     */
+    createHandshakeRequest(agent: AgentLike, toAddress: string, recipientVk: VerifyKey): Promise<Record<string, unknown>>;
+    /**
+     * Handle an inbound handshake message.
+     *
+     * Returns null -- handshake messages are not user-visible.
+     */
+    handleInbound(agent: AgentLike, envelope: MessageEnvelope, senderVk: VerifyKey): Promise<ReceivedMessage | null>;
+    /**
+     * Process a handshake.request: decrypt contact card, apply trust policy.
+     */
+    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;
+    /**
+     * Send a handshake.accept envelope back to the requester.
+     */
+    _sendAccept(agent: AgentLike, toAddress: string, recipientVk: VerifyKey): Promise<void>;
+    /**
+     * Send a handshake.deny envelope to the requester.
+     */
+    _sendDeny(agent: AgentLike, toAddress: string, recipientVk: VerifyKey): Promise<void>;
+}
+
+/**
+ * Abstract transport interface for relay communication.
+ *
+ * Two implementations:
+ * - HTTPTransport: stateless polling via REST API
+ * - WebSocketTransport: persistent real-time connection
+ */
+declare abstract class TransportBase {
+    /** Establish connection to the relay. */
+    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>;
+    /** Retrieve pending messages from the relay. */
+    abstract receive(limit?: number): Promise<Record<string, unknown>[]>;
+    /**
+     * Start listening for real-time messages.
+     *
+     * For WebSocket: registers a callback for push delivery.
+     * For HTTP: not supported (throws Error).
+     */
+    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).
+ *
+ * Provides send(), inbox(), handshake flow, contact management,
+ * trust policies, approve/deny/block/unblock.
+ *
+ * Matches Python agent.py API surface.
+ */
+
+declare class Agent {
+    /** @internal */
+    readonly _config: SDKConfig;
+    /** @internal */
+    readonly _keyManager: KeyManager;
+    /** @internal */
+    _transport: TransportBase | null;
+    private _resolver;
+    private _address;
+    private _token;
+    private _connected;
+    private _autoRegister;
+    /** @internal */
+    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.
+     */
+    constructor(name: string, options?: {
+        relay?: string | null;
+        domain?: string | null;
+        keyDir?: string | null;
+        autoRegister?: boolean;
+        displayName?: string | null;
+        transport?: string;
+        trustPolicy?: string;
+    });
+    /** The agent's full UAM address (e.g., 'myagent::youam.network'). */
+    get address(): string;
+    /** UAM SDK version. */
+    get version(): string;
+    /** The agent's public key (base64-encoded Ed25519 verify key). */
+    get publicKey(): string;
+    /** Whether the agent has completed connection setup. */
+    get isConnected(): boolean;
+    /**
+     * Generate and return a signed contact card for this agent.
+     */
+    contactCard(): Promise<Record<string, unknown>>;
+    /**
+     * Initialize the agent: load/generate keys, register, connect transport.
+     *
+     * Idempotent -- calling twice is safe.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect the transport and clean up resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Send an encrypted, signed message. Returns the message_id.
+     */
+    send(toAddress: string, message: string, options?: {
+        threadId?: string;
+        attachments?: Array<Record<string, unknown>>;
+    }): Promise<string>;
+    /**
+     * Retrieve, decrypt, and verify pending messages.
+     *
+     * Returns a list of ReceivedMessage data objects.
+     * Drops messages with invalid signatures or decryption errors. A message
+     * that fails processing for any other reason (malformed envelope, bad
+     * handshake payload, ...) is logged and dropped; it never aborts the
+     * rest of the batch.
+     */
+    inbox(limit?: number): Promise<ReceivedMessage[]>;
+    /** List pending handshake requests. */
+    pending(): Promise<Array<{
+        address: string;
+        contactCard: string;
+        receivedAt: string;
+    }>>;
+    /**
+     * Approve a pending handshake request.
+     *
+     * Adds the sender to contacts with trust_source='explicit-approval'
+     * and sends handshake.accept back.
+     */
+    approve(address: string): Promise<void>;
+    /**
+     * Deny a pending handshake request.
+     *
+     * Removes the entry from pending and sends handshake.deny.
+     */
+    deny(address: string): Promise<void>;
+    /**
+     * Block an address or domain pattern (HAND-04).
+     */
+    block(pattern: string): Promise<void>;
+    /**
+     * Remove a block pattern (HAND-04).
+     */
+    unblock(pattern: string): Promise<void>;
+    /**
+     * 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.
+     */
+    verifyDomain(domain: string, options?: {
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<boolean>;
+    /** Multi-relay failover (CARD-06). */
+    private _getRelayUrls;
+    /**
+     * 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.
+     */
+    private _trySendWithFailover;
+    private _ensureConnected;
+    /**
+     * 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.
+     */
+    private _resolvePublicKey;
+    private _initiateHandshake;
+    /**
+     * Process a single inbound envelope: verify, decrypt, handle handshakes.
+     *
+     * 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).
+     */
+    private _sweepExpiredHandshakes;
+    /**
+     * 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.
+     */
+    private _sendReadReceipt;
+    /**
+     * Register with the relay server.
+     *
+     * Calls POST /api/v1/register with agent name and public key. If the
+     * address exists (409), repeats it with a proof that this agent holds the
+     * key. Stores the returned API key on disk.
+     */
+    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;
+}
+
+/**
+ * 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 };