@cello-protocol/daemon 0.0.230 → 0.0.231

package/dist/channel-join-exchange.js

@@ -0,0 +1,289 @@
+/**
+ * ChannelJoinExchange — M16 019-MEMBERSHIP Part B, both sides of joining a channel.
+ *
+ * A channel never converses. Its ADMIN is an ordinary agent, so a join is a typed exchange inside a
+ * normal sealed session with that admin — no new transport, no relay frames, no special case in the
+ * session layer.
+ *
+ * ─── The two identity checks, and why each is load-bearing ───────────────────────────────────
+ *
+ * **ADMIN side: the session counterparty must BE the subscriber the frame names.** The frame says
+ * who is joining and the session says who is talking; if they may differ, anyone can enrol a third
+ * party — and, worse, receive that third party's key bundle themselves, because the bundle is
+ * wrapped for the pubkey in the frame and sent down the session they are holding.
+ *
+ * **SUBSCRIBER side: the answering agent must be the admin in the channel's DIRECTORY PROFILE.**
+ * The session proves who the counterparty is. It does not prove they are this channel's admin. Drop
+ * this check and any agent that can open a session with you hands you a key bundle and a relay pair
+ * and becomes your channel: you read their posts believing them to be somebody else's, and the
+ * immutable `admin_pubkey` the design rests on protects nobody.
+ *
+ * ─── What is NOT decided here ────────────────────────────────────────────────────────────────
+ *
+ * Invite-only admission is the admin AGENT's decision. A request lands as `pending` and raises a
+ * notice; nothing in this file approves one. There is no heuristic, no allowlist, no auto-approve.
+ */
+import { decodeChannelJoinRequest, decodeChannelJoinAccepted, decodeChannelRekey, encodeChannelJoinAccepted, encodeChannelJoinRefused, encodeChannelRekey, isChannelJoinFrame, } from "@cello-protocol/protocol-types";
+import { generateGroupKey, wrapGroupKeyFor, unwrapGroupKey, } from "@cello-protocol/crypto";
+import { extractErrorMessage } from "./error-message.js";
+export function createChannelJoinExchange(deps) {
+    const { logger, members, subscriptions } = deps;
+    const now = deps.now ?? (() => Date.now());
+    async function refuseTo(sessionId, channelPubkey, reason) {
+        logger.info("channel.join.refused", {
+            channel_pubkey: Buffer.from(channelPubkey).toString("hex"), reason,
+        });
+        await deps.sendInSession(sessionId, encodeChannelJoinRefused({ channel_pubkey: channelPubkey, reason }));
+    }
+    /**
+     * Mint or reuse this channel's current group key, wrap it for one member, and send the acceptance.
+     *
+     * ⚠️ **THE ADMIN STORES ITS OWN CHANNEL'S GROUP KEY IN THE SAME TABLE ITS SUBSCRIBERS USE**, under
+     * its own agent id. A key held only in this process is lost on restart — and then the second
+     * member admitted after a restart gets a DIFFERENT key at the same generation, so the two decrypt
+     * different halves of the channel and neither can tell why. The admin is a reader of its own
+     * channel; storing the key where readers keep keys is the honest place for it.
+     */
+    function currentGroupKey(adminAgentId, channelHex, generation) {
+        const held = subscriptions.keysFor(adminAgentId, channelHex).find((k) => k.generation === generation);
+        if (held)
+            return held;
+        const minted = generateGroupKey(generation);
+        subscriptions.addKey(adminAgentId, channelHex, minted, now());
+        return minted;
+    }
+    async function acceptInto(sessionId, channelHex, subscriberHex, admin) {
+        const settings = members.settings(channelHex);
+        /**
+         * ⚠️ RETURNS A REASON RATHER THAN NOTHING. This used to return silently, and `approve` reported
+         * `ok: true` on top of it — so an admin believed they had admitted somebody who received no key
+         * and no relays, and the member's daemon heard nothing at all.
+         */
+        if (!settings)
+            return { ok: false, reason: "channel_not_configured_for_membership" };
+        let generation = settings.key_generation;
+        if (generation === 0)
+            generation = members.startGeneration(channelHex);
+        const gk = currentGroupKey(admin.agentId, channelHex, generation);
+        const channelPubkey = await admin.channelKeyProvider.getPublicKey();
+        const bundle = await wrapGroupKeyFor(gk, channelPubkey, new Uint8Array(Buffer.from(subscriberHex, "hex")), admin.adminKeyProvider);
+        await deps.sendInSession(sessionId, encodeChannelJoinAccepted({
+            channel_pubkey: channelPubkey,
+            key_bundle: bundle,
+            guidance: settings.guidance,
+            retention_seconds: settings.retention_seconds,
+            // `public` cannot reach here — the caller refuses it — and the frame refuses it too.
+            access: settings.access === "invite_only" ? "invite_only" : "open",
+            relays: settings.relays,
+            members_visible: settings.members_visible,
+        }));
+        logger.info("channel.member.joined", {
+            channel_pubkey: channelHex, subscriber_pubkey: subscriberHex, generation,
+        });
+        return { ok: true };
+    }
+    return {
+        async onAdminFrame(sessionId, counterpartyHex, content) {
+            // Not a join frame means somebody is TALKING. Consuming it would make a person's message
+            // vanish instead of reaching the operator — the same rule the document router follows.
+            if (!isChannelJoinFrame(content))
+                return { consumed: false };
+            const decoded = decodeChannelJoinRequest(content);
+            if (!decoded.ok) {
+                /**
+                 * ⚠️ LOGGED, because this frame is now GONE. It is consumed — structured traffic, not
+                 * conversation — so it never reaches the operator's transcript. Returning silently meant any
+                 * counterparty could send a CBOR array whose first element was one of the four type strings
+                 * and have it disappear with nothing recorded anywhere. The decoder already produces a
+                 * reason and a detail; there is no excuse for discarding them.
+                 */
+                logger.warn("channel.join.frame_undecodable", {
+                    reason: decoded.reason, detail: decoded.detail, sender: counterpartyHex,
+                });
+                return { consumed: true };
+            }
+            const channelPubkey = decoded.frame.channel_pubkey;
+            const channelHex = Buffer.from(channelPubkey).toString("hex");
+            const namedSubscriber = Buffer.from(decoded.frame.subscriber_pubkey).toString("hex");
+            /**
+             * ⚠️ THE COUNTERPARTY, NOT THE FRAME'S CLAIM. `namedSubscriber` is whatever the caller wrote;
+             * logging it before the check below let a prober put an arbitrary pubkey in an operator's log
+             * and make it look like that party had asked to join. The session's counterparty is the only
+             * identity here that anything has proven.
+             */
+            logger.info("channel.join.requested", {
+                channel_pubkey: channelHex, counterparty_pubkey: counterpartyHex,
+            });
+            /**
+             * ⚠️ **THE COUNTERPARTY MUST BE THE SUBSCRIBER THE FRAME NAMES.** Otherwise anyone can enrol a
+             * third party — and receive that party's key bundle down the session they are holding.
+             * Refused as `not_admin_of_channel` rather than a more specific reason: to a caller who is not
+             * who they claim, "this is not your join" and "this is not my channel" are the same answer,
+             * and a distinct one would tell a prober which channels this daemon administers.
+             */
+            if (namedSubscriber !== counterpartyHex.toLowerCase()) {
+                await refuseTo(sessionId, channelPubkey, "not_admin_of_channel");
+                return { consumed: true };
+            }
+            const admin = deps.localChannelAdmin(channelHex);
+            if (!admin) {
+                await refuseTo(sessionId, channelPubkey, "not_admin_of_channel");
+                return { consumed: true };
+            }
+            const settings = members.settings(channelHex);
+            if (!settings) {
+                await refuseTo(sessionId, channelPubkey, "not_admin_of_channel");
+                return { consumed: true };
+            }
+            // A public channel has no keys and no membership: anyone may read it. Admitting somebody would
+            // record a membership that means nothing and promise a key that does not exist.
+            if (settings.access === "public") {
+                await refuseTo(sessionId, channelPubkey, "channel_is_public");
+                return { consumed: true };
+            }
+            const status = members.statusOf(channelHex, namedSubscriber);
+            if (status === "active") {
+                await refuseTo(sessionId, channelPubkey, "already_member");
+                return { consumed: true };
+            }
+            // ⚠️ AN EJECTED MEMBER CANNOT SIMPLY ASK AGAIN. Re-admitting on request would undo the
+            // ejection the moment they retried — which is exactly why the ejected row is never deleted.
+            if (status === "ejected") {
+                await refuseTo(sessionId, channelPubkey, "ejected");
+                return { consumed: true };
+            }
+            if (status === "pending") {
+                await refuseTo(sessionId, channelPubkey, "pending_approval");
+                return { consumed: true };
+            }
+            if (settings.access === "open") {
+                members.admit(channelHex, namedSubscriber, "active", now());
+                await acceptInto(sessionId, channelHex, namedSubscriber, admin);
+                return { consumed: true };
+            }
+            // invite_only: recorded as PENDING and handed to the admin agent. Nothing here approves it.
+            members.admit(channelHex, namedSubscriber, "pending", now());
+            logger.info("channel.join.pending", { channel_pubkey: channelHex, subscriber_pubkey: namedSubscriber });
+            deps.raiseNotice("channel.join.pending", channelHex, namedSubscriber);
+            await refuseTo(sessionId, channelPubkey, "pending_approval");
+            return { consumed: true };
+        },
+        async onSubscriberFrame(agentId, sessionId, counterpartyHex, content) {
+            if (!isChannelJoinFrame(content))
+                return { ok: false, reason: "not_a_join_frame" };
+            /**
+             * An acceptance OR a re-key. Narrowed into two locals rather than kept as a pair of results,
+             * so the compiler knows which one carries a frame — a non-null assertion here would be the
+             * kind of "I know better" that survives a later edit changing which branch can be reached.
+             */
+            const acceptedResult = decodeChannelJoinAccepted(content);
+            const acceptedFrame = acceptedResult.ok ? acceptedResult.frame : null;
+            let rekeyFrame = null;
+            if (!acceptedFrame) {
+                const rekeyResult = decodeChannelRekey(content);
+                if (rekeyResult.ok)
+                    rekeyFrame = rekeyResult.frame;
+            }
+            if (!acceptedFrame && !rekeyFrame)
+                return { ok: false, reason: "malformed" };
+            const channelPubkey = acceptedFrame ? acceptedFrame.channel_pubkey : rekeyFrame.channel_pubkey;
+            const channelHex = Buffer.from(channelPubkey).toString("hex");
+            /**
+             * ⚠️ **THE ADMIN CHECK, AGAINST THE DIRECTORY PROFILE.** Not against whoever answered: the
+             * session proves identity, not authority. Without this any agent that can open a session with
+             * you becomes your channel, and the immutable admin key protects nobody.
+             *
+             * A lookup that cannot be RESOLVED fails closed. An unreachable directory must never mean
+             * "accept whoever this is" — that would make a network problem into an admission.
+             */
+            /**
+             * ⚠️ **A RE-KEY ASKS NOBODY: the admin was checked when the subscription was made, and is
+             * stored on it.** Going back to the directory for one would put a network round trip, and a
+             * directory outage, in the path of every re-key — and a re-key is how an EJECTION reaches the
+             * remaining members, so losing one is the thing with a cost. It is also what closed the
+             * exposure this check opened: an unsolicited re-key naming any pubkey would otherwise have
+             * bought a stranger a directory lookup, on a handler the session layer is waiting for.
+             *
+             * The asking agent goes with the acceptance case, because the lookup rides THAT agent's own
+             * authenticated directory stream rather than any connection that happens to be open.
+             */
+            const storedAdmin = rekeyFrame ? (subscriptions.get(agentId, channelHex)?.admin_pubkey ?? null) : null;
+            const profileAdmin = storedAdmin ?? await deps.profileAdminPubkey(channelHex, agentId);
+            if (profileAdmin === null) {
+                logger.warn("channel.join.refused", { channel_pubkey: channelHex, reason: "admin_unresolved" });
+                return { ok: false, reason: "admin_unresolved" };
+            }
+            if (profileAdmin.toLowerCase() !== counterpartyHex.toLowerCase()) {
+                logger.warn("channel.join.refused", {
+                    channel_pubkey: channelHex, reason: "not_admin_of_channel",
+                    answered_by: counterpartyHex, profile_admin: profileAdmin,
+                });
+                return { ok: false, reason: "not_admin_of_channel" };
+            }
+            const myKeys = deps.keyProviderFor(agentId);
+            if (!myKeys)
+                return { ok: false, reason: "no_key_provider" };
+            const bundle = acceptedFrame ? acceptedFrame.key_bundle : rekeyFrame.key_bundle;
+            const unwrapped = await unwrapGroupKey(bundle, channelPubkey, myKeys);
+            if (!unwrapped.ok) {
+                logger.warn("channel.join.refused", { channel_pubkey: channelHex, reason: unwrapped.reason });
+                return { ok: false, reason: "key_unwrap_failed" };
+            }
+            // An ACCEPTANCE brings the subscription with it; a RE-KEY only adds a key to one that exists.
+            if (acceptedFrame) {
+                subscriptions.upsert({
+                    agent_id: agentId,
+                    channel_pubkey: channelHex,
+                    admin_pubkey: profileAdmin,
+                    access: acceptedFrame.access,
+                    relays: acceptedFrame.relays,
+                    // STORED, not just decoded. What the channel is for and how long its posts last are the
+                    // two things a subscriber has no other way to learn.
+                    guidance: acceptedFrame.guidance,
+                    retention_seconds: acceptedFrame.retention_seconds,
+                    joined_at: now(),
+                });
+            }
+            subscriptions.addKey(agentId, channelHex, unwrapped.gk, now());
+            return { ok: true, channelHex, generation: unwrapped.gk.generation };
+        },
+        async approve(channelHex, subscriberHex, sessionId) {
+            const admin = deps.localChannelAdmin(channelHex);
+            if (!admin)
+                return { ok: false, reason: "channel_not_local" };
+            try {
+                members.approve(channelHex, subscriberHex);
+            }
+            catch (err) {
+                return { ok: false, reason: extractErrorMessage(err) };
+            }
+            // The delivery's verdict is the ANSWER. Reporting `ok` regardless told an admin they had
+            // admitted somebody who in fact received nothing.
+            return acceptInto(sessionId, channelHex, subscriberHex, admin);
+        },
+        async refuse(channelHex, subscriberHex, sessionId) {
+            const admin = deps.localChannelAdmin(channelHex);
+            if (!admin)
+                return { ok: false, reason: "channel_not_local" };
+            const channelPubkey = await admin.channelKeyProvider.getPublicKey();
+            /**
+             * ⚠️ **CONDITIONAL ON `pending`, AND THAT CONDITION IS THE POINT.** This used to upsert
+             * `ejected` unconditionally, so a refusal typed against an existing MEMBER answered `ok`,
+             * marked them ejected, and left them holding the current group key and fetch key — reading
+             * indefinitely while the table said otherwise. Refusing is not ejecting: an eject re-keys the
+             * channel, and a refusal has nothing to re-key because they were never in.
+             */
+            try {
+                members.refusePending(channelHex, subscriberHex);
+            }
+            catch (err) {
+                return { ok: false, reason: extractErrorMessage(err) };
+            }
+            await refuseTo(sessionId, channelPubkey, "refused_by_admin");
+            return { ok: true };
+        },
+    };
+}
+/** Re-exported so the caller does not need a second import to build a re-key frame. */
+export { encodeChannelRekey };
+//# sourceMappingURL=channel-join-exchange.js.map

package/dist/channel-join-exchange.js.map

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

package/dist/channel-membership-store.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ChannelMembershipStore — the PUBLISHER's record of who is in a channel (M16 019-MEMBERSHIP).
+ *
+ * The mirror of `channel-subscription-store.ts`: that one is what a subscriber knows about somebody
+ * else's channel, this is what an admin knows about its own — the access rule, the members, and the
+ * key generation counter that ejection advances.
+ *
+ * ─── Why an ejected row is never deleted ─────────────────────────────────────────────────────
+ *
+ * Deleting it would make an ejected member indistinguishable from a stranger, so their very next
+ * join request would be admitted as a new one — undoing the ejection silently, which is the one
+ * thing the whole mechanism exists to prevent. The row stays, with `ejected` on it, for ever.
+ *
+ * ─── Why the generation moves in the SAME transaction as the status ──────────────────────────
+ *
+ * An eject that flipped the row and failed to bump the generation is not an eject: every member
+ * including the ejected one keeps reading, and nothing anywhere says the ejection did not take. The
+ * two facts are one fact, so they commit together or neither does.
+ *
+ * Keyed on the channel's pubkey and the member's pubkey — identities, never display names.
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger } from "./types.js";
+import type { ChannelAccess } from "@cello-protocol/protocol-types";
+/**
+ * ⚠️ **THERE IS NO `channel_settings` TABLE, AND THERE MUST NOT BE ONE.** This store first created
+ * its own, duplicating four columns of 018's `channel_config`, and nothing in production ever wrote
+ * a row to it. Every membership read came back empty, so every join was refused
+ * `not_admin_of_channel` on a channel the daemon demonstrably administered, every eject threw
+ * `channel_unknown`, and no group key was ever minted — which meant the fetch key was absent and the
+ * relay served the queue to anyone.
+ *
+ * Two tables holding one fact, with the live path reading the empty one. Collapsed into
+ * `channel_config` while the database was still empty. If you are about to add a second table for a
+ * publisher's decisions about its own channel: that is this bug.
+ */
+import { CHANNEL_CONFIG_CREATE_SQL } from "./channel-config-store.js";
+export { CHANNEL_CONFIG_CREATE_SQL };
+export declare const CHANNEL_MEMBERS_CREATE_SQL = "\n  CREATE TABLE IF NOT EXISTS channel_members (\n    channel_pubkey     TEXT    NOT NULL,\n    subscriber_pubkey  TEXT    NOT NULL,\n    joined_at          INTEGER NOT NULL,\n    -- active | pending | ejected | refused. An ejected row is NEVER deleted \u2014 see the header.\n    status             TEXT    NOT NULL,\n    PRIMARY KEY (channel_pubkey, subscriber_pubkey)\n  );\n";
+/**
+ * `refused` is distinct from `ejected`: one never became a member, the other was removed and cost
+ * the channel a re-key. Collapsing them would make the two indistinguishable in every later read.
+ */
+export type MemberStatus = "active" | "pending" | "ejected" | "refused";
+export interface ChannelSettings {
+    access: ChannelAccess;
+    members_visible: boolean;
+    guidance: string;
+    retention_seconds: number;
+    relays: string[];
+    key_generation: number;
+    /**
+     * The AGENT that admits members and answers join requests. NOT the channel key: the channel signs
+     * posts and never converses; the admin holds the sessions. A subscriber checks the agent that
+     * answered against THIS, so conflating the two makes the check compare a key with itself.
+     */
+    admin_pubkey: string;
+}
+export type ChannelMembershipErrorCode = "channel_unknown" | "not_an_active_member" | "not_a_pending_request" | "eject_not_applicable_open_channel" | "eject_not_applicable_public_channel";
+export declare class ChannelMembershipError extends Error {
+    readonly code: ChannelMembershipErrorCode;
+    constructor(code: ChannelMembershipErrorCode, message: string);
+}
+export declare class ChannelMembershipStore {
+    #private;
+    constructor(db: DaemonDatabase, logger: Logger);
+    /** Create or update a channel's settings. Never touches `key_generation` — only an eject does. */
+    putSettings(channelHex: string, s: Omit<ChannelSettings, "key_generation">, now?: number): void;
+    settings(channelHex: string): ChannelSettings | null;
+    /**
+     * Record a member. `pending` is an invite-only request awaiting the admin agent's decision.
+     *
+     * ⚠️ A PENDING MEMBER RECEIVES NO KEY — `activeMembers` excludes them. Counting a request as a
+     * membership would auto-approve every stranger who asked, and invite-only admission is the admin's
+     * decision, never a heuristic.
+     */
+    admit(channelHex: string, subscriberHex: string, status: MemberStatus, joinedAt: number): void;
+    /** Move a pending request to active. The admin agent's explicit decision, never automatic. */
+    approve(channelHex: string, subscriberHex: string): void;
+    /**
+     * Refuse a PENDING request. Conditional on `pending`, and that condition is the whole method.
+     *
+     * ⚠️ **REFUSING IS NOT EJECTING, AND IT MUST NOT BE ABLE TO ACT LIKE ONE.** An earlier version
+     * upserted `ejected` unconditionally, so an admin who typed a refusal against an existing MEMBER
+     * got `ok: true`, the row said ejected, and the member kept the current group key and fetch key
+     * and went on reading indefinitely. The table and reality disagreed with nothing to say so —
+     * against the order's own rule that an eject without a generation bump is not an eject.
+     *
+     * A refused request gets its own status, not `ejected`: they were never a member, and reusing the
+     * word would make the two indistinguishable in every later read.
+     */
+    refusePending(channelHex: string, subscriberHex: string): void;
+    statusOf(channelHex: string, subscriberHex: string): MemberStatus | null;
+    /** Who a new key goes to. Pending and ejected are excluded, for different reasons — see above. */
+    activeMembers(channelHex: string): string[];
+    /**
+     * Eject a member and advance the generation, atomically.
+     *
+     * Returns the new generation and the members it must be delivered to — the ejected one is simply
+     * not in that list, which is the entire mechanism.
+     *
+     * ⚠️ **AN OPEN CHANNEL CANNOT EJECT**, because the member would rejoin the moment they asked: the
+     * re-key would cost every other member a delivery and change nothing. A PUBLIC channel has no
+     * members at all. Both refuse BY NAME, because a generic failure leaves an admin retrying
+     * something that will never work.
+     *
+     * ⚠️ **EJECTING SOMEBODY WHO IS NOT AN ACTIVE MEMBER MUST NOT BUMP THE GENERATION.** Every bump
+     * re-keys every real member, and every re-key is a delivery that can fail — so a mistyped pubkey
+     * would cost the whole channel a key rotation for nothing.
+     */
+    eject(channelHex: string, subscriberHex: string): {
+        generation: number;
+        remaining: string[];
+    };
+    /** Mint the FIRST generation for a channel that has never issued a key. */
+    startGeneration(channelHex: string): number;
+}
+//# sourceMappingURL=channel-membership-store.d.ts.map

package/dist/channel-membership-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-membership-store.d.ts","sourceRoot":"","sources":["../src/channel-membership-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAErC,eAAO,MAAM,0BAA0B,+XAStC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,aAAa,CAAC;IACtB,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,0BAA0B,GAClC,iBAAiB,GACjB,sBAAsB,GACtB,uBAAuB,GACvB,mCAAmC,GACnC,qCAAqC,CAAC;AAE1C,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;gBAC9B,IAAI,EAAE,0BAA0B,EAAE,OAAO,EAAE,MAAM;CAK9D;AAYD,qBAAa,sBAAsB;;gBAIrB,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM;IAO9C,kGAAkG;IAClG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,gBAAgB,CAAC,EAAE,GAAG,SAAa,GAAG,IAAI;IAkBnG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IA2BpD;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAqB9F,8FAA8F;IAC9F,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAexD;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAkB9D,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAOxE,kGAAkG;IAClG,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE;IAU3C;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE;IA0D7F,2EAA2E;IAC3E,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAM5C"}