@marinoscar/platform-api 0.1.0-next.19 → 0.1.0-next.21

package/dist/webhooks/egress/egress-guard.js

@@ -0,0 +1,172 @@
+"use strict";
+// =============================================================================
+// The webhook egress guard (issue #1046)
+// =============================================================================
+//
+// A webhook URL is typed by an end user and POSTed to by the server: the
+// classic SSRF primitive. Every request therefore passes this guard, at create
+// and update time (a clear 422) and AGAIN at send time (the name may resolve
+// elsewhere by then: DNS rebinding):
+//
+//   1. the URL parses, is `https:` (`http:` only with `allowInsecureHttp`), has
+//      no userinfo, and a port of 80, 443, 8443 or >= 1024;
+//   2. every address the name resolves to (A and AAAA, all of them) is a public
+//      unicast address: no loopback, private, link-local (cloud metadata
+//      169.254.169.254 included), carrier-grade NAT, multicast, unspecified,
+//      documentation or IPv4-mapped/embedded private address;
+//   3. the connection is made to the address that was checked (pinned by the
+//      transport), never to a second lookup of the name.
+//
+// Redirects are never followed (the transport), so a 3xx cannot bounce a
+// checked request to an unchecked target.
+//
+// `allowPrivateTargets` (on-prem, development) turns step 2 and the port rule
+// off; `allowedHosts` exempts exactly the listed host names from step 2.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemHostResolver = exports.WebhookEgressError = void 0;
+exports.parseWebhookUrl = parseWebhookUrl;
+exports.resolveWebhookTarget = resolveWebhookTarget;
+exports.hostForLog = hostForLog;
+const node_dns_1 = require("node:dns");
+const node_net_1 = require("node:net");
+const index_1 = require("../../core/index");
+/**
+ * Thrown by the guard. The message never carries the URL's path or query (only
+ * the host), because a webhook URL may hold a token.
+ *
+ * @stability experimental
+ */
+class WebhookEgressError extends Error {
+    code;
+    constructor(
+    /** The refusal. */
+    code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WebhookEgressError';
+    }
+}
+exports.WebhookEgressError = WebhookEgressError;
+/**
+ * The default resolver: the operating system's (`dns.lookup`, `all: true`), the
+ * same one the connection would use.
+ *
+ * @stability experimental
+ */
+exports.systemHostResolver = {
+    resolveAll: (hostname) => new Promise((resolve, reject) => {
+        (0, node_dns_1.lookup)(hostname, { all: true, verbatim: true }, (error, addresses) => {
+            if (error)
+                reject(error);
+            else
+                resolve(addresses.map((entry) => ({ address: entry.address, family: entry.family === 6 ? 6 : 4 })));
+        });
+    }),
+};
+const ALWAYS_OK_PORTS = new Set([80, 443, 8443]);
+/** Strips the brackets of an IPv6 URL host. */
+function bareHost(url) {
+    const host = url.hostname;
+    return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+}
+/**
+ * The syntactic checks (steps 1): no DNS.
+ *
+ * @param raw - the URL as typed.
+ * @param policy - the guard's policy.
+ * @returns the parsed URL.
+ * @throws WebhookEgressError for a malformed URL, a disallowed scheme, userinfo or a disallowed port.
+ *
+ * @stability experimental
+ */
+function parseWebhookUrl(raw, policy) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new WebhookEgressError('invalid_url', 'The URL is not valid.');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && policy.allowInsecureHttp)) {
+        throw new WebhookEgressError('scheme_not_allowed', url.protocol === 'http:' ? 'The URL must use https.' : 'The URL must be an https URL.');
+    }
+    if (url.username !== '' || url.password !== '') {
+        throw new WebhookEgressError('userinfo_not_allowed', 'The URL must not contain a user name or password.');
+    }
+    if (url.hostname === '')
+        throw new WebhookEgressError('invalid_url', 'The URL has no host.');
+    if (!policy.allowPrivateTargets && url.port !== '') {
+        const port = Number(url.port);
+        if (!ALWAYS_OK_PORTS.has(port) && port < 1024) {
+            throw new WebhookEgressError('port_not_allowed', `Port ${port} is not allowed; use 80, 443, 8443 or a port from 1024.`);
+        }
+    }
+    return url;
+}
+function isExemptHost(hostname, policy) {
+    const lower = hostname.toLowerCase();
+    return policy.allowedHosts.some((allowed) => allowed.toLowerCase() === lower);
+}
+/**
+ * The full guard: {@link parseWebhookUrl}, then resolve every address and
+ * refuse the target when any is not public.
+ *
+ * @param raw - the URL as typed.
+ * @param policy - the guard's policy.
+ * @param resolver - the DNS port.
+ * @returns the checked target, with the address to pin.
+ * @throws WebhookEgressError `private_target` when ANY resolved address is blocked, `unresolvable` when the name has none.
+ *
+ * @stability experimental
+ */
+async function resolveWebhookTarget(raw, policy, resolver) {
+    const url = parseWebhookUrl(raw, policy);
+    const hostname = bareHost(url);
+    const skipChecks = policy.allowPrivateTargets || isExemptHost(hostname, policy);
+    const literal = (0, node_net_1.isIP)(hostname);
+    if (literal !== 0) {
+        if (!skipChecks && (0, index_1.isBlockedAddress)(hostname)) {
+            throw new WebhookEgressError('private_target', `The address ${hostname} is not a public address.`);
+        }
+        return { url, hostname, address: hostname, family: literal === 6 ? 6 : 4 };
+    }
+    const lower = hostname.toLowerCase();
+    if (!skipChecks && (lower === 'localhost' || lower.endsWith('.localhost'))) {
+        throw new WebhookEgressError('private_target', `The host ${hostname} is not a public host.`);
+    }
+    let addresses;
+    try {
+        addresses = await resolver.resolveAll(hostname);
+    }
+    catch {
+        throw new WebhookEgressError('unresolvable', `The host ${hostname} does not resolve.`);
+    }
+    if (addresses.length === 0)
+        throw new WebhookEgressError('unresolvable', `The host ${hostname} does not resolve.`);
+    if (!skipChecks) {
+        const blocked = addresses.find((entry) => (0, index_1.isBlockedAddress)(entry.address));
+        if (blocked)
+            throw new WebhookEgressError('private_target', `The host ${hostname} resolves to a non-public address.`);
+    }
+    const first = addresses[0];
+    return { url, hostname, address: first.address, family: first.family };
+}
+/**
+ * The host of a URL for a log line or a metric: never the path, the query or
+ * the userinfo.
+ *
+ * @param raw - a URL.
+ * @returns the host, or `unknown`.
+ *
+ * @stability experimental
+ */
+function hostForLog(raw) {
+    try {
+        return new URL(raw).host || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=egress-guard.js.map

package/dist/webhooks/egress/egress-guard.js.map

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

package/dist/webhooks/egress/transport.d.ts

@@ -0,0 +1,58 @@
+import type { ResolvedWebhookTarget } from './egress-guard';
+/** One request. @stability experimental */
+export interface WebhookTransportRequest {
+    /** The checked target. */
+    readonly target: ResolvedWebhookTarget;
+    /** The request headers (content type, user agent, the three signing headers). */
+    readonly headers: Readonly<Record<string, string>>;
+    /** The exact body. */
+    readonly body: string;
+    /** The deadline for the whole exchange. */
+    readonly timeoutMs: number;
+}
+/** What came back. @stability experimental */
+export interface WebhookTransportResponse {
+    /** The HTTP status. */
+    readonly status: number;
+    /** The `Retry-After` header, raw, when present. */
+    readonly retryAfter: string | null;
+    /** The first `WEBHOOK_SNIPPET_MAX` characters of the body, control characters removed. */
+    readonly snippet: string;
+}
+/** A transport failure with a stable code. @stability experimental */
+export declare class WebhookTransportError extends Error {
+    /** `timeout` or `network`. */
+    readonly code: 'timeout' | 'network';
+    constructor(
+    /** `timeout` or `network`. */
+    code: 'timeout' | 'network', message: string);
+}
+/**
+ * Sends one request. A port: the default is {@link nodeWebhookTransport}; the
+ * slice's testing entry has a recording fake.
+ *
+ * @stability experimental
+ */
+export interface WebhookTransport {
+    /**
+     * POSTs `request`.
+     *
+     * @param request - the request.
+     * @returns the response.
+     * @throws WebhookTransportError on a timeout or any network failure.
+     */
+    send(request: WebhookTransportRequest): Promise<WebhookTransportResponse>;
+}
+/** Removes control characters and caps the length. */
+export declare function toSnippet(raw: string): string;
+/**
+ * The default transport.
+ *
+ * @stability experimental
+ */
+export declare const nodeWebhookTransport: WebhookTransport;
+/** Injection token of the {@link WebhookTransport}. @stability experimental */
+export declare const WEBHOOKS_TRANSPORT: unique symbol;
+/** Injection token of the {@link HostResolver}. @stability experimental */
+export declare const WEBHOOKS_RESOLVER: unique symbol;
+//# sourceMappingURL=transport.d.ts.map

package/dist/webhooks/egress/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/webhooks/egress/transport.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAE5D,2CAA2C;AAC3C,MAAM,WAAW,uBAAuB;IACtC,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,8CAA8C;AAC9C,MAAM,WAAW,wBAAwB;IACvC,uBAAuB;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,qBAAa,qBAAsB,SAAQ,KAAK;IAE5C,8BAA8B;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS;;IADpC,8BAA8B;IACrB,IAAI,EAAE,SAAS,GAAG,SAAS,EACpC,OAAO,EAAE,MAAM;CAKlB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC3E;AAED,sDAAsD;AACtD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAyElC,CAAC;AAMF,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,EAAE,OAAO,MAA8D,CAAC;AACvG,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAA6D,CAAC"}

package/dist/webhooks/egress/transport.js

@@ -0,0 +1,115 @@
+"use strict";
+// =============================================================================
+// The webhook HTTP transport (issue #1046)
+// =============================================================================
+//
+// One POST to a checked, PINNED address. Node's `http(s).request` with a
+// `lookup` that answers the address the guard approved (so a second DNS answer
+// cannot redirect the connection) while the URL's host name still drives the
+// Host header, the TLS server name and certificate verification. No redirect is
+// followed (the platform's HTTP client never does), the whole exchange has a
+// deadline, and only the first KiB of the response body is read.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOKS_RESOLVER = exports.WEBHOOKS_TRANSPORT = exports.nodeWebhookTransport = exports.WebhookTransportError = void 0;
+exports.toSnippet = toSnippet;
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const webhooks_constants_1 = require("../webhooks.constants");
+/** A transport failure with a stable code. @stability experimental */
+class WebhookTransportError extends Error {
+    code;
+    constructor(
+    /** `timeout` or `network`. */
+    code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'WebhookTransportError';
+    }
+}
+exports.WebhookTransportError = WebhookTransportError;
+/** Removes control characters and caps the length. */
+function toSnippet(raw) {
+    return raw.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '').slice(0, webhooks_constants_1.WEBHOOK_SNIPPET_MAX);
+}
+/**
+ * The default transport.
+ *
+ * @stability experimental
+ */
+exports.nodeWebhookTransport = {
+    send(req) {
+        const { target } = req;
+        const secure = target.url.protocol === 'https:';
+        const pinned = (_hostname, options, callback) => {
+            if (options.all) {
+                callback(null, [{ address: target.address, family: target.family }]);
+            }
+            else {
+                callback(null, target.address, target.family);
+            }
+        };
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (action) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                action();
+            };
+            const options = {
+                method: 'POST',
+                host: target.hostname,
+                port: target.url.port === '' ? (secure ? 443 : 80) : Number(target.url.port),
+                path: `${target.url.pathname}${target.url.search}`,
+                headers: { ...req.headers, 'content-length': String(Buffer.byteLength(req.body)) },
+                lookup: pinned,
+                // Verify the certificate against the host NAME, not the pinned address.
+                ...(secure && !isLiteral(target.hostname) ? { servername: target.hostname } : {}),
+                agent: false,
+            };
+            const clientRequest = (secure ? node_https_1.request : node_http_1.request)(options, (response) => {
+                const chunks = [];
+                let size = 0;
+                const retryAfter = typeof response.headers['retry-after'] === 'string' ? response.headers['retry-after'] : null;
+                const done = () => finish(() => resolve({
+                    status: response.statusCode ?? 0,
+                    retryAfter,
+                    snippet: toSnippet(Buffer.concat(chunks).toString('utf8')),
+                }));
+                response.on('data', (chunk) => {
+                    if (size < webhooks_constants_1.WEBHOOK_SNIPPET_MAX * 4) {
+                        chunks.push(chunk);
+                        size += chunk.length;
+                    }
+                    if (size >= webhooks_constants_1.WEBHOOK_SNIPPET_MAX * 4) {
+                        response.destroy();
+                        done();
+                    }
+                });
+                response.on('end', done);
+                response.on('error', () => done());
+                response.on('close', done);
+            });
+            const timer = setTimeout(() => {
+                finish(() => reject(new WebhookTransportError('timeout', 'The receiver did not answer in time.')));
+                clientRequest.destroy();
+            }, req.timeoutMs);
+            timer.unref?.();
+            clientRequest.on('error', (error) => {
+                // The message may name the host and port; never the path or query.
+                finish(() => reject(new WebhookTransportError('network', `Network error${error.code ? ` (${error.code})` : ''}.`)));
+            });
+            clientRequest.end(req.body);
+        });
+    },
+};
+function isLiteral(host) {
+    return /^[\d.]+$/.test(host) || host.includes(':');
+}
+/** Injection token of the {@link WebhookTransport}. @stability experimental */
+exports.WEBHOOKS_TRANSPORT = Symbol.for('@marinoscar/platform/webhooks/TRANSPORT');
+/** Injection token of the {@link HostResolver}. @stability experimental */
+exports.WEBHOOKS_RESOLVER = Symbol.for('@marinoscar/platform/webhooks/RESOLVER');
+//# sourceMappingURL=transport.js.map

package/dist/webhooks/egress/transport.js.map

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

package/dist/webhooks/handlers/webhook-deliver.handler.d.ts

@@ -0,0 +1,76 @@
+import { type OnModuleInit } from '@nestjs/common';
+import { JobHandlerRegistry, type Job, type JobExecutionProfile, type JobHandler } from '../../jobs/index';
+import { NotificationsService } from '../../notifications/index';
+import { MetricsHostService } from '../../otel-core/index';
+import { type HostResolver } from '../egress/egress-guard';
+import { type WebhookTransport } from '../egress/transport';
+import { WebhookSecrets } from '../webhook-secrets.service';
+import { type ResolvedWebhooksModuleOptions } from '../webhooks.options';
+import { WebhooksRepository } from '../webhooks.repository';
+/**
+ * The delay before the retry that follows failed attempt number `attempt`.
+ *
+ * @param attempt - the attempt that just failed (1-based).
+ * @param retryAfterMs - the receiver's `Retry-After`, when it sent one.
+ * @param rand - a random source in [0, 1), for tests.
+ * @returns milliseconds: the schedule entry with half-range jitter, never less than `Retry-After` (capped at 24 h).
+ *
+ * @stability experimental
+ */
+export declare function retryDelayMs(attempt: number, retryAfterMs?: number | null, rand?: () => number): number;
+/**
+ * Parses a `Retry-After` header: delta-seconds or an HTTP date.
+ *
+ * @param value - the raw header.
+ * @param now - the current time in ms.
+ * @returns milliseconds to wait, or `null` when absent or malformed.
+ *
+ * @stability experimental
+ */
+export declare function parseRetryAfter(value: string | null, now?: number): number | null;
+/**
+ * The `webhooks.deliver` job. See the file header.
+ *
+ * @stability experimental
+ */
+export declare class WebhookDeliverHandler implements JobHandler, OnModuleInit {
+    private readonly registry;
+    private readonly repository;
+    private readonly secrets;
+    private readonly options;
+    private readonly transport;
+    private readonly resolver;
+    private readonly notifications?;
+    private readonly metrics?;
+    private readonly logger;
+    /** PERMANENT once jobs of this type exist. */
+    readonly type = "webhooks.deliver";
+    /** Its name in the jobs console. */
+    readonly label = "Webhook delivery";
+    /** 30 s per run (the request has 10 s); a failed attempt schedules its own retry, so the queue's attempts only cover infrastructure failures. */
+    readonly profile: JobExecutionProfile;
+    /** Overridable clock, for tests. */
+    now: () => Date;
+    /** Overridable random source, for tests. */
+    rand: () => number;
+    constructor(registry: JobHandlerRegistry, repository: WebhooksRepository, secrets: WebhookSecrets, options: ResolvedWebhooksModuleOptions, transport: WebhookTransport, resolver: HostResolver, notifications?: NotificationsService | undefined, metrics?: MetricsHostService | undefined);
+    /** Registers the handler with the job registry. */
+    onModuleInit(): void;
+    /**
+     * Runs one attempt.
+     *
+     * @param job - the claimed job; `subjectId` is the delivery id and `orgId` its organization (`null`: a system endpoint).
+     */
+    process(job: Job): Promise<void>;
+    private attempt;
+    private failed;
+    /** The current secret first, then the previous one while the rotation overlap lasts. */
+    private signingSecrets;
+    private policy;
+    private count;
+    /** After the commit, outside any transaction. */
+    private tellOwner;
+}
+/** The `webhook-*` header names a delivery carries, for the docs and the testing entry. @stability experimental */
+export declare const WEBHOOK_REQUEST_HEADER_NAMES: readonly string[];
+//# sourceMappingURL=webhook-deliver.handler.d.ts.map

package/dist/webhooks/handlers/webhook-deliver.handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-deliver.handler.d.ts","sourceRoot":"","sources":["../../../src/webhooks/handlers/webhook-deliver.handler.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIzF,OAAO,EAAE,kBAAkB,EAAE,KAAK,GAAG,EAAE,KAAK,mBAAmB,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC3G,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAwD,KAAK,YAAY,EAA4B,MAAM,wBAAwB,CAAC;AAC3I,OAAO,EAAgE,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI1H,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAS5D,OAAO,EAAoB,KAAK,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAuB,MAAM,wBAAwB,CAAC;AAEjF;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,GAAE,MAAM,GAAG,IAAW,EAAE,IAAI,GAAE,MAAM,MAAoB,GAAG,MAAM,CAM1H;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAM7F;AAED;;;;GAIG;AACH,qBACa,qBAAsB,YAAW,UAAU,EAAE,YAAY;IAmBlE,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAzBvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0C;IAEjE,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,sBAA4B;IAEzC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,sBAAsB;IAEpC,iJAAiJ;IACjJ,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAA6C;IAElF,oCAAoC;IACpC,GAAG,EAAE,MAAM,IAAI,CAAoB;IAEnC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,MAAM,CAAe;gBAGd,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,kBAAkB,EAC9B,OAAO,EAAE,cAAc,EACG,OAAO,EAAE,6BAA6B,EACpC,SAAS,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,YAAY,EACrC,aAAa,CAAC,EAAE,oBAAoB,YAAA,EACpC,OAAO,CAAC,EAAE,kBAAkB,YAAA;IAG3D,mDAAmD;IACnD,YAAY,IAAI,IAAI;IAIpB;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;YAgDxB,OAAO;IAwErB,OAAO,CAAC,MAAM;IA+Bd,wFAAwF;YAC1E,cAAc;IAY5B,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,KAAK;IAOb,iDAAiD;YACnC,SAAS;CAcxB;AAED,mHAAmH;AACnH,eAAO,MAAM,4BAA4B,mBAA0H,CAAC"}