agent-protocols 0.10.1 → 0.11.0

package/dist/mail-client.js

@@ -0,0 +1,176 @@
+/** Same-origin Mail HTTP client. Packet delivery is anonymous; read/delete require owner-bound JWTs. */
+import { parseStrictJson, validateOrigin } from "./identity.js";
+import { protocolError } from "./errors.js";
+import { HttpResponseError } from "./http-client.js";
+import { MAIL_MAX_PACKET_BYTES, MailCardCache, decodeMailBytes, mailCanonicalBytes, validateMailboxCard, validateMailCardRecord, validateMailDeliveryResult, validateMailDiscovery, validateMailOwnerJwt, validateMailPacket, validateMailPacketList, } from "./mail.js";
+/** Client for one relay origin (a card route). Paths are fixed at `/v1/mailboxes`. */
+export class MailClient {
+    service;
+    options;
+    cardCache;
+    fetchImpl;
+    base;
+    clock;
+    maxResponseBytes;
+    constructor(service, options = {}) {
+        this.service = service;
+        this.options = options;
+        validateOrigin(service);
+        this.cardCache = options.cardCache ?? new MailCardCache();
+        this.fetchImpl = options.fetch ?? fetch;
+        this.clock = options.clock ?? Date.now;
+        this.maxResponseBytes =
+            options.maxResponseBytes ?? 128 * MAIL_MAX_PACKET_BYTES;
+        if (!Number.isSafeInteger(this.maxResponseBytes) ||
+            this.maxResponseBytes < 1)
+            throw protocolError("invalid_request", "invalid response limit");
+        this.base = service + "/v1/mailboxes";
+    }
+    /** Informational discovery document; it never changes delivery paths. */
+    async protocol() {
+        const d = await this.request(this.service + "/.well-known/agent-mail", "GET", 200);
+        validateMailDiscovery(d, this.service);
+        return d;
+    }
+    /** Read and pin the current card, even a closed or expired one. Rollback throws `stale_card`. */
+    async card(mailboxId, owner) {
+        decodeMailBytes(mailboxId, 16);
+        const r = await this.request(`${this.base}/${mailboxId}/card`, "GET", 200);
+        validateMailCardRecord(r, owner, mailboxId);
+        this.cardCache.observe(r.envelope, owner, this.clock(), false);
+        return r;
+    }
+    async publish(card) {
+        validateMailboxCard(card);
+        const r = await this.request(this.base, "POST", 200, card);
+        validateMailCardRecord(r, card.event.actor, card.event.payload.mailbox_id, card.hash);
+        return r;
+    }
+    /** Anonymous delivery or exact retransmission of a completed packet. */
+    async deliver(packet) {
+        validateMailPacket(packet);
+        const r = await this.request(`${this.base}/${packet.header.mailbox_id}/packets`, "POST", 202, packet);
+        validateMailDeliveryResult(r, packet);
+        return r;
+    }
+    async list(mailboxId, owner, jwt, options = {}) {
+        decodeMailBytes(mailboxId, 16);
+        validateMailOwnerJwt(jwt, this.service, owner, this.clock());
+        const limit = options.limit ?? 100;
+        if (!Number.isSafeInteger(limit) ||
+            limit < 1 ||
+            limit > 1000 ||
+            options.cursor === "")
+            throw protocolError("invalid_request", "invalid pagination");
+        const u = new URL(`${this.base}/${mailboxId}/packets`);
+        u.searchParams.set("limit", String(limit));
+        if (options.cursor !== undefined)
+            u.searchParams.set("cursor", options.cursor);
+        const r = await this.request(u.href, "GET", 200, undefined, jwt);
+        validateMailPacketList(r, mailboxId, limit);
+        return r;
+    }
+    /** Every page of one enumeration; `seq` must keep increasing across pages. */
+    async *pages(mailboxId, owner, jwt, limit = 100) {
+        let cursor, seq = 0;
+        do {
+            const page = await this.list(mailboxId, owner, jwt(), { limit, cursor });
+            for (const r of page.result) {
+                if (r.seq <= seq)
+                    throw protocolError("invalid_response", "reordered or repeated page");
+                seq = r.seq;
+            }
+            cursor = page.next_cursor;
+            yield page;
+        } while (cursor !== undefined);
+    }
+    async delete(mailboxId, packetId, owner, jwt) {
+        decodeMailBytes(mailboxId, 16);
+        decodeMailBytes(packetId, 32);
+        validateMailOwnerJwt(jwt, this.service, owner, this.clock());
+        await this.request(`${this.base}/${mailboxId}/packets/${packetId}`, "DELETE", 204, undefined, jwt);
+    }
+    async request(url, method, status, body, jwt) {
+        const target = new URL(url);
+        if (target.origin !== this.service ||
+            target.username ||
+            target.password ||
+            target.hash)
+            throw protocolError("invalid_request", "unsafe Mail URL");
+        if (this.options.allowUrl && !(await this.options.allowUrl(url)))
+            throw protocolError("permission_denied", "URL denied by local network policy");
+        const response = await this.fetchImpl(url, {
+            method,
+            redirect: "error",
+            credentials: "omit",
+            referrerPolicy: "no-referrer",
+            headers: {
+                accept: "application/json",
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+                ...(jwt === undefined ? {} : { authorization: `Bearer ${jwt}` }),
+            },
+            ...(body === undefined
+                ? {}
+                : { body: new TextDecoder().decode(mailCanonicalBytes(body)) }),
+        });
+        if (response.redirected ||
+            (response.status >= 300 && response.status < 400) ||
+            (response.url && response.url !== url))
+            throw protocolError("invalid_response", "redirect or response URL mismatch");
+        const declared = response.headers.get("content-length");
+        if (declared !== null && Number(declared) > this.maxResponseBytes)
+            throw protocolError("invalid_response", "response too large");
+        const reader = response.body?.getReader();
+        const chunks = [];
+        let count = 0;
+        if (reader) {
+            try {
+                for (;;) {
+                    const r = await reader.read();
+                    if (r.done)
+                        break;
+                    count += r.value.length;
+                    if (count > this.maxResponseBytes) {
+                        await reader.cancel();
+                        throw protocolError("invalid_response", "response too large");
+                    }
+                    chunks.push(r.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+        const bytes = new Uint8Array(count);
+        let at = 0;
+        for (const c of chunks) {
+            bytes.set(c, at);
+            at += c.length;
+        }
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        }
+        catch {
+            throw protocolError("invalid_response", "response is not UTF-8");
+        }
+        if (!response.ok)
+            throw new HttpResponseError(response.status, text, response.headers.get("Max-Seen-Nonce") ?? undefined);
+        if (response.status !== status)
+            throw protocolError("invalid_response", `Mail response requires HTTP ${status}`);
+        if (status === 204) {
+            if (text)
+                throw protocolError("invalid_response", "DELETE response must be empty");
+            return undefined;
+        }
+        if (!/^application\/json(?:\s*;|$)/i.test(response.headers.get("content-type") ?? ""))
+            throw protocolError("invalid_response", "response must be application/json");
+        try {
+            return parseStrictJson(text);
+        }
+        catch {
+            throw protocolError("invalid_response", "response violates strict I-JSON");
+        }
+    }
+}
+//# sourceMappingURL=mail-client.js.map

package/dist/mail-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-client.js","sourceRoot":"","sources":["../src/mail-client.ts"],"names":[],"mappings":"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"}

package/dist/mail-schema.d.ts

@@ -0,0 +1,353 @@
+export declare const MAIL_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://agent-protocols.dev/schemas/agent-mail/1.0.schema.json";
+    readonly title: "Agent Mail Protocol 1.0";
+    readonly description: "Structural definitions; signed objects and packets are closed, while Identity list/discovery extensions are retained. Strict I-JSON, Unicode scalar validity, canonical JCS, parsed URL origins, Ed25519 signatures, HPKE and all-zero X25519 checks, byte lengths, cross-field equality, lifetime bounds, reply binding, authorization, and stateful lifecycle requirements need semantic validation; passing this schema is not protocol conformance. Select a named definition for HTTP response objects.";
+    readonly oneOf: readonly [{
+        readonly $ref: "#/$defs/envelope";
+    }, {
+        readonly $ref: "#/$defs/packet";
+    }];
+    readonly $defs: {
+        readonly agentId: {
+            readonly type: "string";
+            readonly pattern: "^did:agent:[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$(?![\\s\\S])";
+        };
+        readonly hash32: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$(?![\\s\\S])";
+        };
+        readonly id16: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9_-]{21}[AQgw]$(?![\\s\\S])";
+        };
+        readonly signature: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9_-]{85}[AQgw]$(?![\\s\\S])";
+        };
+        readonly base64url: {
+            readonly type: "string";
+            readonly pattern: "^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-][AQgw]|[A-Za-z0-9_-]{2}[AEIMQUYcgkosw048])?$(?![\\s\\S])";
+        };
+        readonly timestampMs: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly maximum: 9007199254740991;
+        };
+        readonly positiveSafeInteger: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly maximum: 9007199254740991;
+        };
+        readonly httpsOrigin: {
+            readonly type: "string";
+            readonly pattern: "^https://[^/?#@\\s]+$(?![\\s\\S])";
+            readonly not: {
+                readonly pattern: ":443$(?![\\s\\S])";
+            };
+            readonly description: "Approximate syntax only. Identity canonical HTTPS origin parsing and serialization are a semantic requirement.";
+        };
+        readonly mailboxCardPayload: {
+            readonly type: "object";
+            readonly required: readonly ["mailbox_id", "expires_at", "receive_until", "public_key", "routes", "max_packet_bytes"];
+            readonly properties: {
+                readonly mailbox_id: {
+                    readonly $ref: "#/$defs/id16";
+                };
+                readonly expires_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+                readonly receive_until: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+                readonly public_key: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly routes: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/httpsOrigin";
+                    };
+                    readonly minItems: 0;
+                    readonly maxItems: 8;
+                    readonly uniqueItems: true;
+                };
+                readonly max_packet_bytes: {
+                    readonly type: "integer";
+                    readonly minimum: 4096;
+                    readonly maximum: 1048576;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly part: {
+            readonly type: "object";
+            readonly required: readonly ["media_type", "data"];
+            readonly properties: {
+                readonly media_type: {
+                    readonly type: "string";
+                    readonly maxLength: 127;
+                    readonly pattern: "^[a-z0-9][a-z0-9!#$&^_.+\\-]*/[a-z0-9][a-z0-9!#$&^_.+\\-]*$(?![\\s\\S])";
+                };
+                readonly data: {
+                    readonly $ref: "#/$defs/base64url";
+                };
+                readonly name: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 255;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly messagePayload: {
+            readonly type: "object";
+            readonly required: readonly ["to", "expires_at", "thread_id", "parts"];
+            readonly properties: {
+                readonly to: {
+                    readonly $ref: "#/$defs/agentId";
+                };
+                readonly expires_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+                readonly thread_id: {
+                    readonly $ref: "#/$defs/id16";
+                };
+                readonly parts: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/part";
+                    };
+                    readonly minItems: 1;
+                    readonly maxItems: 32;
+                };
+                readonly subject: {
+                    readonly type: "string";
+                    readonly maxLength: 1024;
+                };
+                readonly in_reply_to: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly reply_card: {
+                    readonly $ref: "#/$defs/mailboxCardEnvelope";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly mailboxCardEvent: {
+            readonly type: "object";
+            readonly required: readonly ["protocol", "type", "actor", "created_at", "nonce", "payload"];
+            readonly properties: {
+                readonly protocol: {
+                    readonly const: "agent-mail/1.0";
+                };
+                readonly type: {
+                    readonly const: "mailbox.publish";
+                };
+                readonly actor: {
+                    readonly $ref: "#/$defs/agentId";
+                };
+                readonly created_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+                readonly nonce: {
+                    readonly $ref: "#/$defs/positiveSafeInteger";
+                };
+                readonly payload: {
+                    readonly $ref: "#/$defs/mailboxCardPayload";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly mailboxCardEnvelope: {
+            readonly type: "object";
+            readonly required: readonly ["event", "hash", "signature"];
+            readonly properties: {
+                readonly event: {
+                    readonly $ref: "#/$defs/mailboxCardEvent";
+                };
+                readonly hash: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly signature: {
+                    readonly $ref: "#/$defs/signature";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly messageEvent: {
+            readonly type: "object";
+            readonly required: readonly ["protocol", "type", "actor", "created_at", "nonce", "payload"];
+            readonly properties: {
+                readonly protocol: {
+                    readonly const: "agent-mail/1.0";
+                };
+                readonly type: {
+                    readonly const: "mail.message";
+                };
+                readonly actor: {
+                    readonly $ref: "#/$defs/agentId";
+                };
+                readonly created_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+                readonly nonce: {
+                    readonly $ref: "#/$defs/positiveSafeInteger";
+                };
+                readonly payload: {
+                    readonly $ref: "#/$defs/messagePayload";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly messageEnvelope: {
+            readonly type: "object";
+            readonly required: readonly ["event", "hash", "signature"];
+            readonly properties: {
+                readonly event: {
+                    readonly $ref: "#/$defs/messageEvent";
+                };
+                readonly hash: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly signature: {
+                    readonly $ref: "#/$defs/signature";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly envelope: {
+            readonly oneOf: readonly [{
+                readonly $ref: "#/$defs/mailboxCardEnvelope";
+            }, {
+                readonly $ref: "#/$defs/messageEnvelope";
+            }];
+        };
+        readonly packetHeader: {
+            readonly type: "object";
+            readonly required: readonly ["protocol", "mailbox_id", "card_hash", "expires_at"];
+            readonly properties: {
+                readonly protocol: {
+                    readonly const: "agent-mail/1.0";
+                };
+                readonly mailbox_id: {
+                    readonly $ref: "#/$defs/id16";
+                };
+                readonly card_hash: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly expires_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly packet: {
+            readonly type: "object";
+            readonly required: readonly ["header", "enc", "ciphertext"];
+            readonly properties: {
+                readonly header: {
+                    readonly $ref: "#/$defs/packetHeader";
+                };
+                readonly enc: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly ciphertext: {
+                    readonly allOf: readonly [{
+                        readonly $ref: "#/$defs/base64url";
+                    }];
+                    readonly minLength: 1387;
+                    readonly maxLength: 1048576;
+                    readonly description: "Decoded length must be >= 1040 and 16 modulo 1024. Total JCS(packet) length must fit the card and protocol limits; these are semantic checks.";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly cardAcceptedRecord: {
+            readonly type: "object";
+            readonly required: readonly ["envelope", "accepted_at"];
+            readonly properties: {
+                readonly envelope: {
+                    readonly $ref: "#/$defs/mailboxCardEnvelope";
+                };
+                readonly accepted_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly deliveryResult: {
+            readonly type: "object";
+            readonly required: readonly ["packet_id", "accepted_at"];
+            readonly properties: {
+                readonly packet_id: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly accepted_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly packetRecord: {
+            readonly type: "object";
+            readonly required: readonly ["packet_id", "packet", "accepted_at", "seq"];
+            readonly properties: {
+                readonly packet_id: {
+                    readonly $ref: "#/$defs/hash32";
+                };
+                readonly packet: {
+                    readonly $ref: "#/$defs/packet";
+                };
+                readonly accepted_at: {
+                    readonly $ref: "#/$defs/timestampMs";
+                };
+                readonly seq: {
+                    readonly $ref: "#/$defs/positiveSafeInteger";
+                };
+            };
+            readonly additionalProperties: false;
+        };
+        readonly packetList: {
+            readonly type: "object";
+            readonly required: readonly ["result"];
+            readonly properties: {
+                readonly result: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly $ref: "#/$defs/packetRecord";
+                    };
+                    readonly minItems: 0;
+                    readonly maxItems: 1000;
+                };
+                readonly next_cursor: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+            readonly additionalProperties: true;
+        };
+        readonly discoveryDocument: {
+            readonly type: "object";
+            readonly required: readonly ["protocol", "service"];
+            readonly properties: {
+                readonly protocol: {
+                    readonly const: "agent-mail/1.0";
+                };
+                readonly service: {
+                    readonly $ref: "#/$defs/httpsOrigin";
+                };
+                readonly features: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly uniqueItems: true;
+                };
+            };
+            readonly additionalProperties: true;
+            readonly description: "Mail defines no endpoint names; delivery paths are fixed at each card route. Other members are inert extensions.";
+        };
+    };
+};
+//# sourceMappingURL=mail-schema.d.ts.map

package/dist/mail-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail-schema.d.ts","sourceRoot":"","sources":["../src/mail-schema.ts"],"names":[],"mappings":"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"}