agent-comms 1.13.0 → 1.15.0

package/dist/core/web-push.js

@@ -0,0 +1,198 @@
+/**
+ * Web Push encryption and VAPID JWT signing (RFC 8291 + RFC 8292).
+ *
+ * Implements the Web Push protocol using only Node.js built-in `crypto`
+ * and `https` — no external dependencies.
+ *
+ * Encryption flow (RFC 8291):
+ *   1. Derive a shared ECDH secret from the subscription's p256dh key
+ *   2. HKDF-derive the encryption key and nonce from the shared secret + auth
+ *   3. Encrypt the payload with AES-128-GCM
+ *   4. Prepend the sender's public key (65 bytes) to the ciphertext
+ *
+ * VAPID signing (RFC 8292):
+ *   1. Build a JWT with { sub, exp, aud } claims
+ *   2. Sign with ES256 (ECDSA + P-256 + SHA-256)
+ *   3. Append the public key and token to the Crypto-Key header
+ */
+import * as crypto from "node:crypto";
+import * as https from "node:https";
+import * as http from "node:http";
+import { URL } from "node:url";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const CONTENT_ENCODING = "aes128gcm";
+const KEY_LENGTH = 16;
+const NONCE_LENGTH = 12;
+const SALT_LENGTH = 16;
+const MAX_PAYLOAD_SIZE = 4078;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Send a Web Push notification.
+ *
+ * Encrypts the payload per RFC 8291, signs with VAPID per RFC 8292,
+ * and POSTs to the push service endpoint.
+ */
+export async function sendWebPush(subscription, payload, vapidKeys, subject) {
+    const plaintext = JSON.stringify(payload);
+    const plaintextBuf = Buffer.from(plaintext, "utf-8");
+    if (plaintextBuf.length > MAX_PAYLOAD_SIZE) {
+        throw new Error(`Payload too large: ${String(plaintextBuf.length)} bytes (max ${String(MAX_PAYLOAD_SIZE)})`);
+    }
+    const encrypted = encrypt(plaintextBuf, subscription.keys);
+    const headers = buildHeaders(encrypted, subscription.endpoint, vapidKeys, subject);
+    await post(subscription.endpoint, headers, encrypted);
+}
+// ---------------------------------------------------------------------------
+// Encryption (RFC 8291)
+// ---------------------------------------------------------------------------
+function encrypt(plaintext, keys) {
+    // Decode the subscription's p256dh and auth keys
+    const recipientPubKey = base64urlDecode(keys.p256dh);
+    const authKey = base64urlDecode(keys.auth);
+    // Generate an ephemeral ECDH key pair for this message
+    const ecdh = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+    const senderPrivateKey = crypto.createPrivateKey({
+        key: ecdh.privateKey.export({ type: "pkcs8", format: "der" }),
+        format: "der",
+        type: "pkcs8",
+    });
+    const senderPublicDer = ecdh.publicKey.export({
+        type: "spki",
+        format: "der",
+    });
+    const senderPublicKey = senderPublicDer.subarray(senderPublicDer.length - 65);
+    // Derive the shared secret via ECDH
+    const sharedSecret = crypto.diffieHellman({
+        privateKey: senderPrivateKey,
+        publicKey: crypto.createPublicKey({
+            key: concat(Buffer.from("3059301306072a8648ce3d020106082a8648ce3d030107034200", "hex"), recipientPubKey),
+            format: "der",
+            type: "spki",
+        }),
+    });
+    // Derive the pseudo-random key (PRK) using HKDF with auth
+    const prk = hkdfExtract(authKey, sharedSecret);
+    // Derive the encryption key and nonce
+    const keyInfo = concat(Buffer.from("Content-Encoding: aes128gcm\0", "utf-8"), senderPublicKey);
+    const nonceInfo = Buffer.from("Content-Encoding: nonce\0", "utf-8");
+    const encryptionKey = hkdfExpand(prk, keyInfo, KEY_LENGTH);
+    const nonce = hkdfExpand(prk, nonceInfo, NONCE_LENGTH);
+    // Generate a random salt
+    const salt = crypto.randomBytes(SALT_LENGTH);
+    // Pad the plaintext: plaintext + 2-byte padding delimiter (0x02 0x00 for no padding)
+    // RFC 8291 §4: record is plaintext || 0x02 || padding zeros
+    const padded = concat(plaintext, Buffer.from([0x02]));
+    // Encrypt with AES-128-GCM
+    const cipher = crypto.createCipheriv("aes-128-gcm", encryptionKey, nonce);
+    const ciphertext = cipher.update(padded);
+    const authTag = cipher.getAuthTag();
+    // RFC 8291 §4: salt (16) || rs (4, big-endian, 4096) || sender pubkey (65) || ciphertext || tag
+    const rs = Buffer.alloc(4);
+    rs.writeUInt32BE(4096);
+    return concat(salt, rs, senderPublicKey, ciphertext, authTag);
+}
+// ---------------------------------------------------------------------------
+// HKDF helpers
+// ---------------------------------------------------------------------------
+function hkdfExtract(salt, ikm) {
+    const hmac = crypto.createHmac("sha256", salt);
+    hmac.update(ikm);
+    return hmac.digest();
+}
+function hkdfExpand(prk, info, length) {
+    const hmac = crypto.createHmac("sha256", prk);
+    hmac.update(concat(info, Buffer.from([0x01])));
+    const t = hmac.digest();
+    return t.subarray(0, length);
+}
+// ---------------------------------------------------------------------------
+// VAPID JWT signing (RFC 8292)
+// ---------------------------------------------------------------------------
+function buildVapidJwt(audience, vapidKeys, subject) {
+    const header = base64url(Buffer.from('{"alg":"ES256","typ":"JWT"}', "utf-8"));
+    const exp = Math.floor(Date.now() / 1000) + 12 * 60 * 60; // 12 hours
+    const claims = JSON.stringify({ aud: audience, exp, sub: subject });
+    const payload = base64url(Buffer.from(claims, "utf-8"));
+    const signInput = `${header}.${payload}`;
+    // Reconstruct the private key from the raw 32-byte scalar
+    // P-256 PKCS8 DER wrapper: 39 bytes header + 32 bytes scalar (with 0x00 prefix)
+    const privScalar = base64urlDecode(vapidKeys.privateKey);
+    // Build the EC private key in SEC1 DER format
+    const sec1Der = concat(Buffer.from("30770201010420", "hex"), privScalar, Buffer.from("a00a06082a8648ce3d030107a14403420004", "hex"), base64urlDecode(vapidKeys.publicKey));
+    const privateKey = crypto.createPrivateKey({
+        key: sec1Der,
+        format: "der",
+        type: "sec1",
+    });
+    const signature = crypto.sign("sha256", Buffer.from(signInput), privateKey);
+    // ECDSA signature is a DER-encoded SEQUENCE of two INTEGERs.
+    // Web Push requires base64url encoding of the raw DER.
+    const sigB64 = base64url(signature);
+    return `${signInput}.${sigB64}`;
+}
+// ---------------------------------------------------------------------------
+// HTTP headers
+// ---------------------------------------------------------------------------
+function buildHeaders(encrypted, endpoint, vapidKeys, subject) {
+    const audience = new URL(endpoint).origin;
+    const jwt = buildVapidJwt(audience, vapidKeys, subject);
+    return {
+        "Content-Type": "application/octet-stream",
+        "Content-Encoding": CONTENT_ENCODING,
+        "Content-Length": String(encrypted.length),
+        Authorization: `vapid t=${jwt}, k=${vapidKeys.publicKey}`,
+        TTL: "86400",
+        Urgency: "high",
+    };
+}
+// ---------------------------------------------------------------------------
+// HTTP POST
+// ---------------------------------------------------------------------------
+function post(endpoint, headers, body) {
+    return new Promise((resolve, reject) => {
+        const url = new URL(endpoint);
+        const isHttps = url.protocol === "https:";
+        const mod = isHttps ? https : http;
+        const req = mod.request({
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: url.pathname + url.search,
+            method: "POST",
+            headers,
+        }, (res) => {
+            // Drain the response body
+            const chunks = [];
+            res.on("data", (chunk) => chunks.push(chunk));
+            res.on("end", () => {
+                if (res.statusCode !== undefined &&
+                    (res.statusCode < 200 || res.statusCode > 299)) {
+                    const body = Buffer.concat(chunks).toString("utf-8");
+                    reject(new Error(`Push service returned ${String(res.statusCode)}: ${body}`));
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+        req.on("error", reject);
+        req.write(body);
+        req.end();
+    });
+}
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+function base64urlDecode(input) {
+    return Buffer.from(input, "base64url");
+}
+function base64url(input) {
+    return input.toString("base64url");
+}
+function concat(...buffers) {
+    return Buffer.concat(buffers);
+}
+//# sourceMappingURL=web-push.js.map

package/dist/core/web-push.js.map

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

package/dist/core/wire-protocol.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Wire protocol — framing, encoding, and message types for the TCP mesh.
+ *
+ * Transport-agnostic: carries the protocol contract between peers without
+ * depending on net.Socket or any specific transport implementation.
+ * TcpTransport, TlsTransport, and WebSocketTransport all use these types.
+ */
+import type { AgentIdentity, DeliveryEvent, DmMessage, Room, RoomMessage } from "./types.js";
+export interface PeerInfo {
+    id: string;
+    port: number;
+    startedAt: string;
+}
+export interface SerialisedState {
+    agents: Record<string, AgentIdentity>;
+    rooms: Record<string, Room>;
+    messages: Record<string, RoomMessage[]>;
+    dms: Record<string, DmMessage[]>;
+}
+export type MeshStatePatch = {
+    type: "agent_upsert";
+    agent: AgentIdentity;
+} | {
+    type: "agent_offline";
+    agentId: string;
+} | {
+    type: "room_upsert";
+    room: Room;
+} | {
+    type: "room_delete";
+    roomId: string;
+} | {
+    type: "message_add";
+    roomId: string;
+    message: RoomMessage;
+} | {
+    type: "dm_add";
+    key: string;
+    message: DmMessage;
+} | {
+    type: "delivery";
+    agentId: string;
+    event: DeliveryEvent;
+} | {
+    type: "message_read";
+    messageId: string;
+    readBy: string;
+    room?: string;
+};
+export type MeshMessage = {
+    method: "state_sync";
+    state: SerialisedState;
+} | {
+    method: "state_update";
+    patch: MeshStatePatch;
+} | {
+    method: "introduce";
+    peerId: string;
+    dataPort: number;
+} | {
+    method: "connect_request";
+    peerId: string;
+    dataPort: number;
+    name: string;
+    fingerprint: string;
+} | {
+    method: "connect_accepted";
+    peerId: string;
+    dataPort: number;
+} | {
+    method: "connect_rejected";
+    peerId: string;
+    reason: string;
+} | {
+    method: "peer_list";
+    peers: PeerInfo[];
+} | {
+    method: "peer_joined";
+    peer: PeerInfo;
+} | {
+    method: "peer_left";
+    peerId: string;
+} | {
+    method: "become_coordinator";
+    peerList: PeerInfo[];
+} | {
+    method: "pong";
+    peerId: string;
+} | {
+    method: "fed_handshake";
+    meshId: string;
+    name: string;
+    version: string;
+} | {
+    method: "fed_ack";
+    meshId: string;
+    name: string;
+    version: string;
+} | {
+    method: "fed_agent_visible";
+    agent: AgentIdentity;
+} | {
+    method: "fed_agent_gone";
+    agentId: string;
+} | {
+    method: "fed_room_message";
+    roomId: string;
+    message: RoomMessage;
+} | {
+    method: "fed_room_join";
+    roomId: string;
+    agentId: string;
+    agentName: string;
+} | {
+    method: "fed_room_leave";
+    roomId: string;
+    agentId: string;
+} | {
+    method: "fed_ping";
+} | {
+    method: "fed_pong";
+};
+export declare function encode(msg: MeshMessage): string;
+export declare class MessageBuffer {
+    private buffer;
+    append(data: string): unknown[];
+}
+export declare function isMeshMessage(value: unknown): value is MeshMessage;
+/** Deterministic key for a DM conversation between two agents. */
+export declare function dmKey(a: string, b: string): string;
+//# sourceMappingURL=wire-protocol.d.ts.map

package/dist/core/wire-protocol.d.ts.map

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

package/dist/core/wire-protocol.js

@@ -0,0 +1,54 @@
+/**
+ * Wire protocol — framing, encoding, and message types for the TCP mesh.
+ *
+ * Transport-agnostic: carries the protocol contract between peers without
+ * depending on net.Socket or any specific transport implementation.
+ * TcpTransport, TlsTransport, and WebSocketTransport all use these types.
+ */
+// ---------------------------------------------------------------------------
+// Framing — newline-delimited JSON
+// ---------------------------------------------------------------------------
+export function encode(msg) {
+    return JSON.stringify(msg) + "\n";
+}
+export class MessageBuffer {
+    buffer = "";
+    append(data) {
+        this.buffer += data;
+        const results = [];
+        let idx = this.buffer.indexOf("\n");
+        while (idx !== -1) {
+            const line = this.buffer.slice(0, idx);
+            this.buffer = this.buffer.slice(idx + 1);
+            if (line.length > 0) {
+                try {
+                    results.push(JSON.parse(line));
+                }
+                catch {
+                    /* skip malformed lines */
+                }
+            }
+            idx = this.buffer.indexOf("\n");
+        }
+        return results;
+    }
+}
+// ---------------------------------------------------------------------------
+// Type guard
+// ---------------------------------------------------------------------------
+export function isMeshMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (!("method" in value))
+        return false;
+    return typeof value.method === "string";
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Deterministic key for a DM conversation between two agents. */
+export function dmKey(a, b) {
+    const sorted = [a, b].sort();
+    return `${sorted[0] ?? a}--${sorted[1] ?? b}`;
+}
+//# sourceMappingURL=wire-protocol.js.map

package/dist/core/wire-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-protocol.js","sourceRoot":"","sources":["../../src/core/wire-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmFH,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAE9E,MAAM,UAAU,MAAM,CAAC,GAAgB;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;AACpC,CAAC;AAED,MAAM,OAAO,aAAa;IAChB,MAAM,GAAG,EAAE,CAAC;IAEpB,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;QACpB,MAAM,OAAO,GAAc,EAAE,CAAC;QAC9B,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YACzC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC;oBACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjC,CAAC;gBAAC,MAAM,CAAC;oBACP,0BAA0B;gBAC5B,CAAC;YACH,CAAC;YACD,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,IAAI,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,CAAC;AAC1C,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,kEAAkE;AAClE,MAAM,UAAU,KAAK,CAAC,CAAS,EAAE,CAAS;IACxC,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AAChD,CAAC"}

package/dist/core/ws-transport.d.ts

@@ -0,0 +1,71 @@
+/**
+ * WebSocketTransport — WebSocket transport for the peer mesh.
+ *
+ * Carries the same wire protocol as TcpTransport but over WebSocket frames.
+ * Each WS frame is a complete JSON message — no newline delimiter or
+ * MessageBuffer needed. This enables browser-based peers (PWAs) to
+ * participate in the mesh.
+ *
+ * The transport is a drop-in replacement for TcpTransport. Same interface,
+ * same wire protocol, same event callbacks. MeshStore cannot tell the
+ * difference.
+ */
+import type { MeshMessage, PeerInfo } from "./wire-protocol.js";
+import type { ConnectionHandle, ListenerInfo, MeshTransport, TransportEvents } from "./transport.js";
+export declare class WebSocketTransport implements MeshTransport {
+    private dataServer;
+    private _dataPort;
+    private coordinatorServer;
+    private _isCoordinator;
+    private coordinatorWs;
+    private peerConnections;
+    private dataServerSockets;
+    private coordinatorServerSockets;
+    private introConnections;
+    private pendingConnections;
+    private shutDown;
+    private _peerId;
+    private readonly events;
+    constructor(events: TransportEvents);
+    get dataPort(): number;
+    get isCoordinator(): boolean;
+    startDataServer(): Promise<void>;
+    connectToCoordinator(host: string, port: number, peerId: string, localDataPort: number): Promise<void>;
+    connectToRemote(host: string, port: number, peerId: string, _localDataPort: number, name: string, fingerprint: string): Promise<void>;
+    becomeCoordinator(host: string, port: number): Promise<void>;
+    connectToPeer(peer: PeerInfo, ownPeerId: string): Promise<void>;
+    send(handle: ConnectionHandle, message: MeshMessage): Promise<void>;
+    acceptConnection(handle: ConnectionHandle): Promise<void>;
+    rejectConnection(handle: ConnectionHandle, reason: string): Promise<void>;
+    broadcast(message: MeshMessage): Promise<void>;
+    addListener(): Promise<string>;
+    removeListener(): Promise<void>;
+    listListeners(): ListenerInfo[];
+    shutdown(): Promise<void>;
+    unref(): void;
+    /**
+     * Handles messages received on the coordinator client socket (the
+     * connection from this peer TO the coordinator). Fires the appropriate
+     * TransportEvents for peer_list, peer_joined, and become_coordinator.
+     */
+    private dispatchCoordinatorClientMessage;
+    /**
+     * Routes a message received on a peer data connection to the
+     * appropriate event. become_coordinator has its own event; all
+     * other messages fire onMessage for MeshStore to handle.
+     */
+    private dispatchDataMessage;
+    /**
+     * Accepts a new connection on the coordinator server. Reads
+     * introduce messages and fires onIntroduction so MeshStore can
+     * respond with the peer list and broadcast the arrival.
+     */
+    private handleCoordinatorServerConnection;
+    /**
+     * Accepts a new connection on the data server. Reads the initial
+     * pong to identify the peer, then fires onMessage for subsequent
+     * messages. Tracks the connection for cleanup on close/error.
+     */
+    private handleIncomingDataConnection;
+}
+//# sourceMappingURL=ws-transport.d.ts.map

package/dist/core/ws-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-transport.d.ts","sourceRoot":"","sources":["../../src/core/ws-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,eAAe,EAChB,MAAM,gBAAgB,CAAC;AA8BxB,qBAAa,kBAAmB,YAAW,aAAa;IAEtD,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,SAAS,CAAK;IAGtB,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,cAAc,CAAS;IAG/B,OAAO,CAAC,aAAa,CAAwB;IAG7C,OAAO,CAAC,eAAe,CAAgC;IAGvD,OAAO,CAAC,iBAAiB,CAAwB;IAGjD,OAAO,CAAC,wBAAwB,CAAwB;IAKxD,OAAO,CAAC,gBAAgB,CAAgC;IAGxD,OAAO,CAAC,kBAAkB,CAStB;IAGJ,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,OAAO,CAAM;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,eAAe;IAMnC,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,aAAa,IAAI,OAAO,CAE3B;IAMK,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IA0BhC,oBAAoB,CACxB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;IAuDV,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC;IAoEV,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB5D,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD/D,IAAI,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnE,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BzD,gBAAgB,CACpB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAkBV,SAAS,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB9C,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAI9B,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC,aAAa,IAAI,YAAY,EAAE;IAQzB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C/B,KAAK,IAAI,IAAI;IAUb;;;;OAIG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;;;OAIG;IACH,OAAO,CAAC,iCAAiC;IA4CzC;;;;OAIG;IACH,OAAO,CAAC,4BAA4B;CAiDrC"}