@youam/sdk 0.2.1 → 0.4.0

package/dist/index.d.cts

@@ -108,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.
@@ -378,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.
  *
@@ -388,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;
@@ -396,6 +522,8 @@ 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;
@@ -407,32 +535,45 @@ 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;
@@ -441,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_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 };
+  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 };
 }
 
 /**
@@ -533,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).
@@ -696,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 {
@@ -758,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>[]>;
     /**
@@ -897,12 +1069,17 @@ 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.
      *
@@ -1092,4 +1269,4 @@ declare class Agent {
  */
 declare function verifyWebhookSignature(payload: Buffer | Uint8Array, signatureHeader: string, secret: string): boolean;
 
-export { Agent, ContactBook, type ReceivedMessage, index as protocol, verifyWebhookSignature };
+export { Agent, ContactBook, PENDING_NOTE, type ReceivedMessage, SEND_STATUSES, type SendResult, type SendStatus, pendingNote, index as protocol, supports, verifyWebhookSignature };

package/dist/index.d.ts

@@ -108,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.
@@ -378,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.
  *
@@ -388,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;
@@ -396,6 +522,8 @@ 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;
@@ -407,32 +535,45 @@ 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;
@@ -441,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_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 };
+  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 };
 }
 
 /**
@@ -533,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).
@@ -696,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 {
@@ -758,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>[]>;
     /**
@@ -897,12 +1069,17 @@ 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.
      *
@@ -1092,4 +1269,4 @@ declare class Agent {
  */
 declare function verifyWebhookSignature(payload: Buffer | Uint8Array, signatureHeader: string, secret: string): boolean;
 
-export { Agent, ContactBook, type ReceivedMessage, index as protocol, verifyWebhookSignature };
+export { Agent, ContactBook, PENDING_NOTE, type ReceivedMessage, SEND_STATUSES, type SendResult, type SendStatus, pendingNote, index as protocol, supports, verifyWebhookSignature };