@torkbot/sandbox 0.1.0-pre.0 → 0.1.0

package/README.md

@@ -1,3 +1,240 @@
-# @torkbot/sandbox
+# Sandbox
 
-Bootstrap placeholder for npm trusted publishing setup. This is not a usable release.
+Sandbox is a TypeScript-first Node.js library for spawning libkrun-backed microVMs.
+
+The target shape is:
+
+- boot a guest from a prebuilt read-only rootfs artifact, likely EROFS,
+- mount host-implemented virtual filesystems,
+- intercept guest HTTP request headers through host TypeScript hooks,
+- communicate with guest init over a bidirectional transport,
+- ship as a statically linked host artifact.
+
+```ts
+import {
+  acceptPublicInternet,
+  acceptTcp,
+  binding,
+  linuxOverlayFs,
+  mount,
+  prebuiltRootfs,
+  projectInit,
+  projectKernel,
+  scratchFs,
+  createSandbox,
+  type SandboxWritableFileSystem,
+} from "@torkbot/sandbox";
+
+declare const workspaceFs: SandboxWritableFileSystem;
+
+await using sandbox = createSandbox({
+  kernel: projectKernel(),
+  init: projectInit(),
+  rootfs: linuxOverlayFs({
+    lower: prebuiltRootfs("dist/rootfs/sandbox.erofs", { format: "erofs" }),
+    upper: scratchFs(),
+  }),
+
+  mounts: [
+    mount("/sandbox", {
+      async stat(path) {
+        if (path === "/") {
+          return {
+            type: "directory",
+            sizeBytes: null,
+            mediaType: null,
+            modifiedAtMs: null,
+          };
+        }
+
+        if (path === "/status.json") {
+          const body = JSON.stringify({ ready: true });
+          return {
+            type: "file",
+            sizeBytes: Buffer.byteLength(body),
+            mediaType: "application/json",
+            modifiedAtMs: null,
+          };
+        }
+
+        throw new Error(`missing path ${path}`);
+      },
+
+      async list(path) {
+        if (path !== "/") throw new Error(`missing directory ${path}`);
+        return [{ name: "status.json", type: "file" }];
+      },
+
+      async read(input) {
+        if (input.path !== "/status.json") {
+          throw new Error(`unknown virtual file: ${input.path}`);
+        }
+
+        return Buffer.from(JSON.stringify({ ready: true }));
+      },
+    }),
+  ],
+
+  bindings: [
+    binding("/workspace", workspaceFs),
+  ],
+
+  network: {
+    outbound: {
+      policy: "deny",
+      rules: [
+        acceptTcp({ cidr: "127.0.0.1/32", ports: [8080] }),
+        acceptPublicInternet({ ports: [443] }),
+      ],
+    },
+  },
+});
+
+sandbox.http.onRequest({ origin: "https://api.github.com" }, (request) => {
+  request.headers.set("authorization", `Bearer ${process.env.GITHUB_TOKEN}`);
+});
+
+await using vm = await sandbox.run();
+```
+
+Incremental guest operations are explicit:
+
+```ts
+const result = await vm.control.exec({
+  id: "tests",
+  argv: ["node", "--test", "test/**/*.test.ts"],
+});
+
+if (result.exitCode !== 0) {
+  throw new Error(result.stderr);
+}
+```
+
+Mounted filesystems expose both the raw callback shape and a host-side tool surface for agent workflows:
+
+```ts
+const sandboxProc = vm.mounts.virtualFs("/sandbox");
+const statusBytes = await sandboxProc.read({
+  path: "/status.json",
+  signal: AbortSignal.timeout(1_000),
+});
+
+console.log(JSON.parse(Buffer.from(statusBytes).toString("utf8")));
+
+const workspace = vm.mounts.host("/workspace");
+
+const notes = await workspace.read({
+  path: "notes.md",
+  offset: 1,
+  limit: 80,
+});
+
+await workspace.write({
+  path: "plan.md",
+  content: "# Plan\n\nStart here.\n",
+});
+
+await workspace.patch({
+  path: "plan.md",
+  edits: [{ oldText: "Start here.", newText: "Ship the narrow slice." }],
+});
+
+const grep = await workspace.bash({
+  command: "grep \"Ship\" plan.md",
+  timeoutMs: 1_000,
+});
+```
+
+Root filesystems are immutable by default. A writable root is expressed as an explicit Linux overlayfs composition:
+
+```ts
+await using sandbox = createSandbox({
+  kernel: projectKernel(),
+  init: projectInit(),
+  rootfs: linuxOverlayFs({
+    lower: prebuiltRootfs("dist/rootfs/base.erofs", { format: "erofs" }),
+    upper: scratchFs(),
+  }),
+});
+
+await using vm = await sandbox.run();
+
+await vm.control.exec({
+  id: "install-toolchain",
+  argv: ["/bin/sh", "-lc", "apk add --no-cache git nodejs"],
+});
+```
+
+`mount(...)` means a guest-visible mount boundary. `binding(...)` means a host-side attachment point into the same filesystem abstraction and does not create a guest mount.
+
+The guest contract is intentionally narrow:
+
+- `/` is read-only unless the rootfs is a `linuxOverlayFs(...)` composition.
+- `/sandbox` is implemented by the host.
+- HTTP request-header hooks are registered in TypeScript and enforced by the Rust host data plane.
+- Network egress starts from deny; outbound rules opt in the exact protocols, ranges, and ports the guest can reach.
+- The HTTP interception CA is generated and injected by Sandbox. Callers provide request-header hooks, not certificate plumbing.
+
+## Design Targets
+
+- no dynamic `libkrun` or `libkrunfw` dependency in the final host artifact,
+- a signed `sandbox-host` process for the Node/Rust host boundary,
+- custom guest init owned by this repo,
+- implicit fd-backed host control sockets owned by Sandbox,
+- avoid host filesystem coordination unless it is intrinsic to the artifact; prefer file descriptors, database handles, bytes, and async iterables over paths,
+- build-time rootfs shaping, with prebuilt rootfs artifacts supplied at VM instantiation,
+- root filesystem composition through small explicit primitives such as `linuxOverlayFs(...)` and `scratchFs()`, with lower and upper expressed as filesystem values,
+- `mount(...)` only for guest-visible mounts; `binding(...)` only for host-side attachment points,
+- programmable virtual filesystems backed by TypeScript callbacks,
+- transparent HTTP interception with TypeScript request-header hooks,
+- default-deny outbound networking with explicit accept rules for protocols, CIDR ranges, public internet reachability, and ports,
+- Rust-native or statically linkable networking components; sidecar network daemons are references, not default runtime dependencies,
+- macOS HVF entitlement signing verified as part of the integration test flow.
+
+## Repository Layout
+
+- `src/`: TypeScript API consumed by Node.js callers.
+- `crates/sandbox-host`: signed VM-host helper used for macOS HVF launch.
+- `crates/sandbox`: Rust host implementation that owns the libkrun boundary and host services.
+- `crates/sandbox-init`: custom guest init used to configure the guest before supervising untrusted code.
+- `tests/e2e`: TypeScript e2e scenarios run directly by Node.js 24+ type stripping.
+
+See [docs/architecture.md](docs/architecture.md) for the initial design.
+
+Kernel artifacts are built separately from runtime VM creation. See [docs/kernel-build.md](docs/kernel-build.md) for the Docker-based `deps/libkrunfw` build entrypoint.
+See [docs/testing-strategy.md](docs/testing-strategy.md) for the integration and e2e verification plan.
+
+## Publishing
+
+The npm package is published as `@torkbot/sandbox`. It does not use post-install scripts. The root package contains the TypeScript API and declares platform artifacts as optional dependencies:
+
+- `@torkbot/sandbox-darwin-arm64`
+- `@torkbot/sandbox-linux-x64-gnu`
+
+Each platform package contains the N-API binding and the `sandbox-host` helper for that target. Runtime artifact resolution only loads the installed optional dependency for the current platform. Local development uses the same layout by materializing the current platform package under `node_modules`.
+
+### macOS signing setup
+
+For now, the macOS `sandbox-host` artifact is not Developer ID signed or notarized. This is an explicit, possibly temporary workaround for publishing before this project has an Apple Developer account.
+
+macOS users must sign the installed helper locally before launching a VM:
+
+```sh
+npx @torkbot/sandbox setup-macos
+```
+
+This performs an ad-hoc local `codesign` with the `com.apple.security.hypervisor` entitlement required by Hypervisor.framework. It does not contact Apple and does not require an Apple Developer account. If a macOS user tries to launch a VM before running setup, Sandbox throws a runtime error that points back to this command.
+
+The release workflow verifies the tag, builds platform packages on their native runners, publishes the platform packages first, and then publishes the root package. That keeps the installable root package from pointing at missing optional artifacts while staying as close as npm allows to a single coordinated release operation.
+
+Local release packaging sanity check:
+
+```sh
+npm run release:pack
+```
+
+After rebuilding local native artifacts, refresh the local optional package layout with:
+
+```sh
+npm run artifacts:link-current
+```

package/dist/artifacts.d.ts

@@ -0,0 +1,12 @@
+type SandboxTarget = {
+    readonly packageName: string;
+    readonly hostBinaryName: string;
+    readonly platform: NodeJS.Platform;
+    readonly arch: NodeJS.Architecture;
+    readonly libc?: "glibc";
+};
+export declare function currentSandboxTarget(): SandboxTarget;
+export declare function hostBinaryPath(): string;
+export declare function rawHostBinaryPath(): string;
+export {};
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAKA,KAAK,aAAa,GAAG;IACnB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAkBF,wBAAgB,oBAAoB,IAAI,aAAa,CAYpD;AAED,wBAAgB,cAAc,IAAI,MAAM,CAIvC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C"}

package/dist/artifacts.js

@@ -0,0 +1,77 @@
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+const require = createRequire(import.meta.url);
+const targets = [
+    {
+        packageName: "@torkbot/sandbox-darwin-arm64",
+        hostBinaryName: "sandbox-host",
+        platform: "darwin",
+        arch: "arm64",
+    },
+    {
+        packageName: "@torkbot/sandbox-linux-x64-gnu",
+        hostBinaryName: "sandbox-host",
+        platform: "linux",
+        arch: "x64",
+        libc: "glibc",
+    },
+];
+export function currentSandboxTarget() {
+    const target = targets.find((candidate) => {
+        return candidate.platform === process.platform && candidate.arch === process.arch;
+    });
+    if (target === undefined) {
+        throw new Error(`unsupported native sandbox target: ${process.platform}-${process.arch}`);
+    }
+    return target;
+}
+export function hostBinaryPath() {
+    const path = rawHostBinaryPath();
+    assertMacosHostIsSigned(path);
+    return path;
+}
+export function rawHostBinaryPath() {
+    const target = currentSandboxTarget();
+    return resolveArtifactPath(target, target.hostBinaryName);
+}
+function resolveArtifactPath(target, artifactName) {
+    try {
+        return require.resolve(`${target.packageName}/${artifactName}`);
+    }
+    catch (error) {
+        const installError = error instanceof Error ? error.message : String(error);
+        throw new Error(`missing ${target.packageName} artifact ${artifactName}; reinstall @torkbot/sandbox for ${process.platform}-${process.arch}, or run npm run artifacts:link-current after building local artifacts. ${installError}`);
+    }
+}
+function assertMacosHostIsSigned(path) {
+    if (process.platform !== "darwin") {
+        return;
+    }
+    let entitlements;
+    const result = spawnSync("codesign", ["-d", "--entitlements", ":-", path], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error !== undefined) {
+        throw new Error(macosSigningError(path, result.error.message));
+    }
+    if (result.status !== 0) {
+        throw new Error(macosSigningError(path, `${result.stdout}\n${result.stderr}`.trim()));
+    }
+    entitlements = `${result.stdout}\n${result.stderr}`;
+    if (!entitlements.includes("<key>com.apple.security.hypervisor</key>")) {
+        throw new Error(macosSigningError(path, "missing com.apple.security.hypervisor entitlement"));
+    }
+}
+function macosSigningError(path, detail) {
+    return [
+        "sandbox-host is not signed for macOS Hypervisor.framework access.",
+        "",
+        "Run this once after installing @torkbot/sandbox:",
+        "  npx @torkbot/sandbox setup-macos",
+        "",
+        `Artifact: ${path}`,
+        `Reason: ${detail}`,
+    ].join("\n");
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { hostBinaryPath, rawHostBinaryPath } from "./artifacts.js";
+const execFileAsync = promisify(execFile);
+const macosHypervisorEntitlements = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "https://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.hypervisor</key>
+  <true/>
+</dict>
+</plist>
+`;
+const command = process.argv[2];
+if (command === "setup-macos") {
+    await setupMacos();
+}
+else {
+    console.error("usage: sandbox setup-macos");
+    process.exit(2);
+}
+async function setupMacos() {
+    if (process.platform !== "darwin") {
+        console.error("sandbox setup-macos is only needed on macOS.");
+        return;
+    }
+    const hostPath = rawHostBinaryPath();
+    const tempDir = await mkdtemp(join(tmpdir(), "torkbot-sandbox-entitlements-"));
+    const entitlementsPath = join(tempDir, "macos-hvf.plist");
+    try {
+        await writeFile(entitlementsPath, macosHypervisorEntitlements);
+        await execFileAsync("codesign", [
+            "--force",
+            "--sign",
+            "-",
+            "--entitlements",
+            entitlementsPath,
+            hostPath,
+        ]);
+        hostBinaryPath();
+        console.log(`Signed sandbox-host for macOS Hypervisor.framework access: ${hostPath}`);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnE,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,2BAA2B,GAAG;;;;;;;;CAQnC,CAAC;AAEF,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAEhC,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;IAC9B,MAAM,UAAU,EAAE,CAAC;AACrB,CAAC;KAAM,CAAC;IACN,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAC5C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,KAAK,UAAU,UAAU;IACvB,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC9D,OAAO;IACT,CAAC;IAED,MAAM,QAAQ,GAAG,iBAAiB,EAAE,CAAC;IACrC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,+BAA+B,CAAC,CAAC,CAAC;IAC/E,MAAM,gBAAgB,GAAG,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAE1D,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,gBAAgB,EAAE,2BAA2B,CAAC,CAAC;QAC/D,MAAM,aAAa,CAAC,UAAU,EAAE;YAC9B,SAAS;YACT,QAAQ;YACR,GAAG;YACH,gBAAgB;YAChB,gBAAgB;YAChB,QAAQ;SACT,CAAC,CAAC;QAEH,cAAc,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,8DAA8D,QAAQ,EAAE,CAAC,CAAC;IACxF,CAAC;YAAS,CAAC;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC"}

package/dist/control-codec.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxControlCommand, SandboxControlEvent } from "./index.ts";
+export declare function encodeControlCommand(command: SandboxControlCommand): Uint8Array;
+export declare function decodeControlEvent(packet: Uint8Array): SandboxControlEvent;
+//# sourceMappingURL=control-codec.d.ts.map

package/dist/control-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-codec.d.ts","sourceRoot":"","sources":["../src/control-codec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE7E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,UAAU,CAU/E;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,mBAAmB,CAwB1E"}

package/dist/control-codec.js

@@ -0,0 +1,88 @@
+import { Binary, BSON } from "bson";
+export function encodeControlCommand(command) {
+    switch (command.type) {
+        case "guest.exec":
+            return encodePacket({
+                type: "guest.exec",
+                id: command.id,
+                argv: [...command.argv],
+                env: Object.entries(command.env ?? {}).map(([key, value]) => ({ key, value })),
+            });
+    }
+}
+export function decodeControlEvent(packet) {
+    const document = decodePacket(packet);
+    const frameType = readString(document, "type");
+    switch (frameType) {
+        case "init.ready":
+            return {
+                type: "init.ready",
+                guest: {
+                    root: { readonly: readBoolean(document, "rootReadonly") },
+                    init: { name: readString(document, "initName") },
+                },
+            };
+        case "guest.exec.complete":
+            return {
+                type: "guest.exec.complete",
+                id: readString(document, "id"),
+                exitCode: readNumber(document, "exitCode"),
+                stdout: new TextDecoder().decode(readBytes(document, "stdout")),
+                stderr: new TextDecoder().decode(readBytes(document, "stderr")),
+            };
+        default:
+            throw new Error(`unknown control frame type: ${frameType}`);
+    }
+}
+function encodePacket(document) {
+    const frame = BSON.serialize(document);
+    const packet = new Uint8Array(4 + frame.byteLength);
+    new DataView(packet.buffer, packet.byteOffset, 4).setUint32(0, frame.byteLength, true);
+    packet.set(frame, 4);
+    return packet;
+}
+function decodePacket(packet) {
+    if (packet.byteLength < 4) {
+        throw new Error("control packet missing length prefix");
+    }
+    const frameLength = new DataView(packet.buffer, packet.byteOffset, 4).getUint32(0, true);
+    if (packet.byteLength < 4 + frameLength) {
+        throw new Error("control packet body is truncated");
+    }
+    if (packet.byteLength !== 4 + frameLength) {
+        throw new Error("control packet has trailing bytes");
+    }
+    return BSON.deserialize(packet.subarray(4));
+}
+function readString(document, key) {
+    const value = document[key];
+    if (typeof value !== "string") {
+        throw new Error(`control frame field must be a string: ${key}`);
+    }
+    return value;
+}
+function readBoolean(document, key) {
+    const value = document[key];
+    if (typeof value !== "boolean") {
+        throw new Error(`control frame field must be a boolean: ${key}`);
+    }
+    return value;
+}
+function readNumber(document, key) {
+    const value = document[key];
+    if (typeof value !== "number") {
+        throw new Error(`control frame field must be a number: ${key}`);
+    }
+    return value;
+}
+function readBytes(document, key) {
+    const value = document[key];
+    if (value instanceof Binary) {
+        return value.buffer;
+    }
+    if (value instanceof Uint8Array) {
+        return value;
+    }
+    throw new Error(`control frame field must be binary: ${key}`);
+}
+//# sourceMappingURL=control-codec.js.map

package/dist/control-codec.js.map

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

package/dist/control.d.ts

@@ -0,0 +1,24 @@
+import type { SandboxControl, SandboxControlCommand, SandboxControlEvent } from "./index.ts";
+export interface HostControlChannel {
+    writeControlPacket(packet: Uint8Array): void;
+    tryReadControlPacket(): Uint8Array | null;
+}
+export declare class HostControlTransport implements SandboxControl {
+    #private;
+    readonly incoming: AsyncIterable<SandboxControlEvent>;
+    constructor(options?: {
+        readonly connected?: boolean;
+        readonly channel?: HostControlChannel;
+    });
+    send(message: SandboxControlCommand): Promise<void>;
+    exec(input: {
+        readonly id?: string;
+        readonly argv: readonly string[];
+        readonly env?: Record<string, string>;
+    }): Promise<Extract<SandboxControlEvent, {
+        type: "guest.exec.complete";
+    }>>;
+    close(): Promise<void>;
+    emit(event: SandboxControlEvent): void;
+}
+//# sourceMappingURL=control.d.ts.map

package/dist/control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.ts","sourceRoot":"","sources":["../src/control.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC7C,oBAAoB,IAAI,UAAU,GAAG,IAAI,CAAC;CAC3C;AAED,qBAAa,oBAAqB,YAAW,cAAc;;IACzD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;IAWtD,YAAY,OAAO,GAAE;QACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;KAClC,EAeL;IAEK,IAAI,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMxD;IAEK,IAAI,CAAC,KAAK,EAAE;QAChB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACvC,GAAG,OAAO,CAAC,OAAO,CAAC,mBAAmB,EAAE;QAAE,IAAI,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC,CAqBzE;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAQ3B;IAED,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAGrC;CAuEF"}