@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/app/services/storage/DiskStorageAdapter.js

@@ -0,0 +1,295 @@
+import { createReadStream } from "node:fs";
+import { lstat, mkdir, readdir, readFile, readlink, realpath, rm, stat, writeFile, } from "node:fs/promises";
+import * as path from "node:path";
+import { Readable } from "node:stream";
+export class DiskStorageAdapter {
+    rootDir;
+    /**
+     * Lazily-resolved real path of `rootDir`. Cached because the root
+     * doesn't move at runtime — and recomputing it per I/O call would
+     * stat the entire root-prefix chain every time.
+     */
+    realRootCache;
+    constructor(opts) {
+        this.rootDir = path.resolve(opts.rootDir);
+    }
+    // ── path helpers ────────────────────────────────────────────────────
+    /**
+     * Resolve a key to an absolute filesystem path, refusing path traversal.
+     * String-based check only — see `resolveKeySafe` for the realpath-based
+     * defense against symlink escapes.
+     */
+    resolveKey(key) {
+        if (!key || key === "/" || key.startsWith("/")) {
+            throw new Error(`DiskStorageAdapter: invalid key "${key}"`);
+        }
+        const normalized = path.posix.normalize(key);
+        if (normalized.startsWith("../") || normalized === ".." || normalized.includes("/../")) {
+            throw new Error(`DiskStorageAdapter: key escapes root: "${key}"`);
+        }
+        const dataPath = path.join(this.rootDir, normalized);
+        if (!dataPath.startsWith(this.rootDir + path.sep) && dataPath !== this.rootDir) {
+            throw new Error(`DiskStorageAdapter: resolved path escapes root: "${dataPath}"`);
+        }
+        return { dataPath, metaPath: `${dataPath}.meta.json` };
+    }
+    /**
+     * `resolveKey` after a realpath-pass that defeats symlink escapes —
+     * critical for multi-tenant deployments on shared filesystems (NFS,
+     * shared k8s volumes) where one tenant's upload directory could
+     * contain a symlink pointing at another tenant's prefix. The pure
+     * string check in `resolveKey` is sound against `..` patterns but
+     * doesn't notice symlinks.
+     *
+     * Strategy: find the deepest existing ancestor of the target path,
+     * `realpath` it (resolving any symlinks along the way), then
+     * re-check that the canonical absolute path is still inside
+     * `realRootDir`. New-key writes work because the "deepest existing
+     * ancestor" is usually the parent directory of the new file.
+     *
+     * `lstat` (not `stat`) is the gate so a symlink whose target is
+     * missing is still detected — we want the symlink itself to count
+     * as "exists" for the walk, then realpath resolves it.
+     */
+    async resolveKeySafe(key) {
+        const { dataPath } = this.resolveKey(key);
+        // Walk up from dataPath until we hit a path that exists (incl.
+        // as a symlink — dangling or otherwise). Accumulate the
+        // non-existing suffix labels for re-joining to the realpath of
+        // the deepest existing ancestor.
+        let probe = dataPath;
+        const suffix = [];
+        let probeIsSymlink = false;
+        while (true) {
+            try {
+                const lst = await lstat(probe);
+                probeIsSymlink = lst.isSymbolicLink();
+                break;
+            }
+            catch (err) {
+                if (err.code !== "ENOENT")
+                    throw err;
+                const parent = path.dirname(probe);
+                if (parent === probe)
+                    break; // hit filesystem root
+                suffix.unshift(path.basename(probe));
+                probe = parent;
+            }
+        }
+        let realProbe;
+        if (probeIsSymlink) {
+            // Resolve the symlink ourselves so a dangling target (realpath
+            // would throw ENOENT and silently fall back to root) still
+            // surfaces as an escape attempt.
+            const linkTarget = await readlink(probe);
+            const absoluteTarget = path.isAbsolute(linkTarget)
+                ? linkTarget
+                : path.join(path.dirname(probe), linkTarget);
+            // Canonicalize the parent directory (the parent does exist —
+            // probe lives in it). The leaf is the symlink target's basename.
+            const realParent = await realpath(path.dirname(absoluteTarget));
+            realProbe = path.join(realParent, path.basename(absoluteTarget));
+        }
+        else {
+            try {
+                realProbe = await realpath(probe);
+            }
+            catch (err) {
+                if (err.code === "ENOENT") {
+                    // Race: the path disappeared between lstat and realpath.
+                    // Fall back to the cached rootDir realpath.
+                    realProbe = await this.getRealRoot();
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        const realDataPath = suffix.length === 0 ? realProbe : path.join(realProbe, ...suffix);
+        const realRoot = await this.getRealRoot();
+        if (!realDataPath.startsWith(realRoot + path.sep) && realDataPath !== realRoot) {
+            throw new Error(`DiskStorageAdapter: realpath escapes root: "${realDataPath}" (key "${key}")`);
+        }
+        return { dataPath: realDataPath, metaPath: `${realDataPath}.meta.json` };
+    }
+    async getRealRoot() {
+        if (this.realRootCache !== undefined)
+            return this.realRootCache;
+        try {
+            this.realRootCache = await realpath(this.rootDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                // rootDir hasn't been created yet — fall back to the
+                // string-resolved form. First `put` will create it.
+                this.realRootCache = this.rootDir;
+            }
+            else {
+                throw err;
+            }
+        }
+        return this.realRootCache;
+    }
+    /** Convert any StorageBody into a Buffer (DiskStorageAdapter buffers fully). */
+    async bodyToBuffer(body) {
+        if (Buffer.isBuffer(body))
+            return body;
+        if (body instanceof Uint8Array)
+            return Buffer.from(body);
+        if (body instanceof Blob) {
+            // Covers File too (File extends Blob).
+            return Buffer.from(await body.arrayBuffer());
+        }
+        if (typeof body.getReader === "function") {
+            const reader = body.getReader();
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value)
+                    chunks.push(value);
+            }
+            return Buffer.concat(chunks);
+        }
+        throw new Error("DiskStorageAdapter: unsupported body type");
+    }
+    // ── StorageService impl ─────────────────────────────────────────────
+    async put(key, body, opts = {}) {
+        const { dataPath, metaPath } = await this.resolveKeySafe(key);
+        await mkdir(path.dirname(dataPath), { recursive: true });
+        const buf = await this.bodyToBuffer(body);
+        await writeFile(dataPath, buf);
+        const sidecar = {
+            contentType: opts.contentType,
+            cacheControl: opts.cacheControl,
+            metadata: opts.metadata,
+        };
+        // Only write the sidecar if any of the fields are present; saves clutter.
+        if (sidecar.contentType || sidecar.cacheControl || sidecar.metadata) {
+            await writeFile(metaPath, JSON.stringify(sidecar, null, 2));
+        }
+        const stats = await stat(dataPath);
+        return {
+            key,
+            size: stats.size,
+            contentType: opts.contentType,
+            lastModified: stats.mtime,
+            metadata: opts.metadata,
+        };
+    }
+    async get(key) {
+        const { dataPath, metaPath } = await this.resolveKeySafe(key);
+        let stats;
+        try {
+            stats = await stat(dataPath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        let sidecar = {};
+        try {
+            sidecar = JSON.parse(await readFile(metaPath, "utf8"));
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        const nodeStream = createReadStream(dataPath);
+        const stream = Readable.toWeb(nodeStream);
+        const meta = {
+            key,
+            size: stats.size,
+            contentType: sidecar.contentType,
+            lastModified: stats.mtime,
+            metadata: sidecar.metadata,
+        };
+        return { stream, meta };
+    }
+    async exists(key) {
+        const { dataPath } = await this.resolveKeySafe(key);
+        try {
+            await stat(dataPath);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+    }
+    async delete(key) {
+        const { dataPath, metaPath } = await this.resolveKeySafe(key);
+        await rm(dataPath, { force: true });
+        await rm(metaPath, { force: true });
+    }
+    /**
+     * Recursive listing of `rootDir`. `prefix` is matched against the
+     * key (not the absolute path); `continuationToken` is an opaque numeric
+     * cursor of how many entries have been emitted so far.
+     *
+     * For local-disk semantics this is fine; production cloud adapters
+     * carry stronger pagination guarantees.
+     */
+    async list(prefix = "", opts = {}) {
+        const maxKeys = opts.maxKeys ?? 1000;
+        const startAfter = opts.continuationToken ? Number.parseInt(opts.continuationToken, 10) : 0;
+        const allKeys = await this.walkKeys(this.rootDir, "");
+        const filtered = allKeys.filter((k) => k.startsWith(prefix)).sort();
+        const slice = filtered.slice(startAfter, startAfter + maxKeys);
+        const objects = [];
+        for (const key of slice) {
+            // Skip entries whose canonical path escapes the root — defends
+            // against symlinked entries that walkKeys couldn't classify
+            // (rare; walkKeys uses Dirent.isFile() which is false for
+            // symlinks, but a TOCTOU race could still surface one here).
+            let dataPath;
+            try {
+                ({ dataPath } = await this.resolveKeySafe(key));
+            }
+            catch {
+                continue;
+            }
+            const stats = await stat(dataPath);
+            objects.push({
+                key,
+                size: stats.size,
+                lastModified: stats.mtime,
+            });
+        }
+        const nextOffset = startAfter + slice.length;
+        return {
+            objects,
+            nextContinuationToken: nextOffset < filtered.length ? String(nextOffset) : undefined,
+        };
+    }
+    /**
+     * Yields all keys (relative paths) under `dir`. Skips `.meta.json`
+     * sidecars so they don't appear as separate objects.
+     */
+    async walkKeys(dir, relPrefix) {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        const out = [];
+        for (const entry of entries) {
+            const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                out.push(...(await this.walkKeys(path.join(dir, entry.name), rel)));
+            }
+            else if (entry.isFile() && !entry.name.endsWith(".meta.json")) {
+                out.push(rel);
+            }
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=DiskStorageAdapter.js.map

package/lib/app/services/storage/DiskStorageAdapter.js.map

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

package/lib/app/services/storage/GCSStorageAdapter.d.ts

@@ -0,0 +1,44 @@
+import type { Bucket } from "@google-cloud/storage";
+import type { GetResult, ListOptions, ListResult, PutOptions, SignedUrlOptions, StorageBody, StorageObjectMeta, StorageService } from "./StorageService.js";
+/**
+ * Google Cloud Storage `StorageService` adapter.
+ *
+ * Wraps a `Bucket` from `@google-cloud/storage`. Sixth Summit's GCP
+ * default. Consumers install the SDK and pass a constructed `Bucket`
+ * (e.g., `new Storage().bucket("name")`).
+ *
+ * `signedUrl` uses GCS's V4 signing (`getSignedUrl({ version: 'v4', ... })`).
+ *
+ * The GCS SDK uses Buffers and Streams natively. `put` accepts the
+ * framework's full `StorageBody` union and normalizes to a Buffer for
+ * `file.save(...)`.
+ */
+export interface GCSStorageAdapterOptions {
+    /** A `Bucket` instance from `@google-cloud/storage`. */
+    bucket: Bucket;
+    /** Optional prefix prepended to every key. */
+    keyPrefix?: string;
+    /**
+     * Maximum TTL (in seconds) accepted by `signedUrl`. Defaults to
+     * **86 400 (24 h)**. Requests with `expiresInSec` exceeding this
+     * ceiling throw `BadRequestError`. See `SignedUrlOptions.expiresInSec`
+     * for the multi-tenant rationale.
+     */
+    maxExpiresInSec?: number;
+}
+export declare class GCSStorageAdapter implements StorageService {
+    private bucket;
+    private keyPrefix;
+    private maxExpiresInSec;
+    constructor(opts: GCSStorageAdapterOptions);
+    private k;
+    private unk;
+    private bodyToBuffer;
+    put(key: string, body: StorageBody, opts?: PutOptions): Promise<StorageObjectMeta>;
+    get(key: string): Promise<GetResult | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, opts?: ListOptions): Promise<ListResult>;
+    signedUrl(key: string, opts?: SignedUrlOptions): Promise<string>;
+}
+//# sourceMappingURL=GCSStorageAdapter.d.ts.map

package/lib/app/services/storage/GCSStorageAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GCSStorageAdapter.d.ts","sourceRoot":"","sources":["../../../../src/app/services/storage/GCSStorageAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACf,MAAM,qBAAqB,CAAC;AAS7B;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,wBAAwB;IACvC,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,iBAAkB,YAAW,cAAc;IACtD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAS;gBAEpB,IAAI,EAAE,wBAAwB;IAW1C,OAAO,CAAC,CAAC;IAIT,OAAO,CAAC,GAAG;YAIG,YAAY;IAiBpB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAmBtF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IA2B3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,MAAM,SAAK,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA0B9D,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;CAiB3E"}

package/lib/app/services/storage/GCSStorageAdapter.js

@@ -0,0 +1,133 @@
+import { BadRequestError } from "../../../http/errors/BadRequestError.js";
+/**
+ * Default upper bound on `signedUrl` TTL in seconds. 24 hours — see
+ * the rationale in `SignedUrlOptions.expiresInSec`. Override
+ * per-adapter via `GCSStorageAdapterOptions.maxExpiresInSec`.
+ */
+const DEFAULT_MAX_EXPIRES_IN_SEC = 86_400;
+export class GCSStorageAdapter {
+    bucket;
+    keyPrefix;
+    maxExpiresInSec;
+    constructor(opts) {
+        this.bucket = opts.bucket;
+        this.keyPrefix = opts.keyPrefix ?? "";
+        this.maxExpiresInSec = opts.maxExpiresInSec ?? DEFAULT_MAX_EXPIRES_IN_SEC;
+        if (this.maxExpiresInSec <= 0) {
+            throw new Error(`GCSStorageAdapter: maxExpiresInSec must be positive (got ${this.maxExpiresInSec})`);
+        }
+    }
+    k(key) {
+        return this.keyPrefix + key;
+    }
+    unk(gcsName) {
+        return gcsName.startsWith(this.keyPrefix) ? gcsName.slice(this.keyPrefix.length) : gcsName;
+    }
+    async bodyToBuffer(body) {
+        if (Buffer.isBuffer(body))
+            return body;
+        if (body instanceof Uint8Array)
+            return Buffer.from(body);
+        if (body instanceof Blob)
+            return Buffer.from(await body.arrayBuffer());
+        if (typeof body.getReader === "function") {
+            const reader = body.getReader();
+            const chunks = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value)
+                    chunks.push(value);
+            }
+            return Buffer.concat(chunks);
+        }
+        throw new Error("GCSStorageAdapter: unsupported body type");
+    }
+    async put(key, body, opts = {}) {
+        const buf = await this.bodyToBuffer(body);
+        const file = this.bucket.file(this.k(key));
+        await file.save(buf, {
+            metadata: {
+                contentType: opts.contentType,
+                cacheControl: opts.cacheControl,
+                metadata: opts.metadata,
+            },
+            resumable: buf.byteLength > 5 * 1024 * 1024, // resumable upload above 5 MB
+        });
+        return {
+            key,
+            size: buf.byteLength,
+            contentType: opts.contentType,
+            metadata: opts.metadata,
+        };
+    }
+    async get(key) {
+        const file = this.bucket.file(this.k(key));
+        const [exists] = await file.exists();
+        if (!exists)
+            return null;
+        const [metadata] = await file.getMetadata();
+        const nodeStream = file.createReadStream();
+        // node:stream Readable → Web ReadableStream
+        const stream = (await import("node:stream")).Readable.toWeb(nodeStream);
+        const size = typeof metadata.size === "string" ? Number.parseInt(metadata.size, 10) : (metadata.size ?? 0);
+        const lastModified = metadata.updated ? new Date(metadata.updated) : undefined;
+        return {
+            stream,
+            meta: {
+                key,
+                size,
+                contentType: metadata.contentType,
+                lastModified,
+                etag: metadata.etag,
+                metadata: metadata.metadata,
+            },
+        };
+    }
+    async exists(key) {
+        const [exists] = await this.bucket.file(this.k(key)).exists();
+        return exists;
+    }
+    async delete(key) {
+        await this.bucket.file(this.k(key)).delete({ ignoreNotFound: true });
+    }
+    async list(prefix = "", opts = {}) {
+        const [files, nextQuery] = await this.bucket.getFiles({
+            prefix: this.k(prefix),
+            maxResults: opts.maxKeys ?? 1000,
+            pageToken: opts.continuationToken,
+            autoPaginate: false,
+        });
+        const objects = files.map((file) => {
+            const m = file.metadata;
+            const size = typeof m.size === "string" ? Number.parseInt(m.size, 10) : (m.size ?? 0);
+            return {
+                key: this.unk(file.name),
+                size,
+                contentType: m.contentType,
+                lastModified: m.updated ? new Date(m.updated) : undefined,
+                etag: m.etag,
+            };
+        });
+        return {
+            objects,
+            nextContinuationToken: nextQuery?.pageToken,
+        };
+    }
+    async signedUrl(key, opts = {}) {
+        const expiresInSec = opts.expiresInSec ?? 900;
+        if (expiresInSec <= 0 || expiresInSec > this.maxExpiresInSec) {
+            throw new BadRequestError(`Signed URL TTL out of range: ${expiresInSec}s (must be > 0 and <= ${this.maxExpiresInSec}s)`);
+        }
+        const action = opts.method === "PUT" ? "write" : "read";
+        const [url] = await this.bucket.file(this.k(key)).getSignedUrl({
+            version: "v4",
+            action,
+            expires: Date.now() + expiresInSec * 1000,
+            contentType: action === "write" ? opts.contentType : undefined,
+        });
+        return url;
+    }
+}
+//# sourceMappingURL=GCSStorageAdapter.js.map

package/lib/app/services/storage/GCSStorageAdapter.js.map

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

package/lib/app/services/storage/S3StorageAdapter.d.ts

@@ -0,0 +1,57 @@
+import { type S3Client } from "@aws-sdk/client-s3";
+import type { GetResult, ListOptions, ListResult, PutOptions, SignedUrlOptions, StorageBody, StorageObjectMeta, StorageService } from "./StorageService.js";
+/**
+ * AWS S3 `StorageService` adapter.
+ *
+ * Wraps an `S3Client` from `@aws-sdk/client-s3`. Consumers install the SDK
+ * (it's not a framework runtime dep — see `package.json` devDependencies)
+ * and pass a constructed client. The adapter calls `client.send(...)` with
+ * the relevant command per StorageService method.
+ *
+ * `signedUrl` uses `@aws-sdk/s3-request-presigner.getSignedUrl` which
+ * generates a properly-signed URL without requiring the file to exist
+ * (useful for browser-direct PUT uploads).
+ *
+ * Buckets, keys, and `keyPrefix` are passed verbatim to the SDK — the
+ * adapter does NOT add a leading "/" or sanitize. Consumers should
+ * sanitize paths upstream (the framework's parseUpload schema is the
+ * recommended choke point).
+ */
+export interface S3StorageAdapterOptions {
+    /** A constructed `S3Client` from `@aws-sdk/client-s3`. */
+    client: S3Client;
+    /** Bucket name. */
+    bucket: string;
+    /** Optional prefix prepended to every key (e.g., `"prod/uploads/"`). */
+    keyPrefix?: string;
+    /**
+     * Maximum TTL (in seconds) accepted by `signedUrl`. Defaults to
+     * **86 400 (24 h)**. Requests with `expiresInSec` exceeding this
+     * ceiling throw `BadRequestError`; the multi-tenant rationale is
+     * documented on `SignedUrlOptions.expiresInSec`.
+     *
+     * Adopters who need longer-lived URLs (e.g., a static-asset bucket
+     * fronting a CDN where leakage is not a concern) raise this
+     * deliberately. Adopters who want shorter URLs (e.g., 1h
+     * compliance ceiling) set this lower.
+     */
+    maxExpiresInSec?: number;
+}
+export declare class S3StorageAdapter implements StorageService {
+    private client;
+    private bucket;
+    private keyPrefix;
+    private maxExpiresInSec;
+    constructor(opts: S3StorageAdapterOptions);
+    private k;
+    /** Strip the prefix from a key returned by the SDK so callers see what they asked for. */
+    private unk;
+    private bodyToS3;
+    put(key: string, body: StorageBody, opts?: PutOptions): Promise<StorageObjectMeta>;
+    get(key: string): Promise<GetResult | null>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    list(prefix?: string, opts?: ListOptions): Promise<ListResult>;
+    signedUrl(key: string, opts?: SignedUrlOptions): Promise<string>;
+}
+//# sourceMappingURL=S3StorageAdapter.d.ts.map

package/lib/app/services/storage/S3StorageAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3StorageAdapter.d.ts","sourceRoot":"","sources":["../../../../src/app/services/storage/S3StorageAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACf,MAAM,qBAAqB,CAAC;AAU7B;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,MAAM,EAAE,QAAQ,CAAC;IACjB,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,gBAAiB,YAAW,cAAc;IACrD,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,eAAe,CAAS;gBAEpB,IAAI,EAAE,uBAAuB;IAYzC,OAAO,CAAC,CAAC;IAIT,0FAA0F;IAC1F,OAAO,CAAC,GAAG;YAIG,QAAQ;IAiBhB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoBtF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAgC3C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,IAAI,CAAC,MAAM,SAAK,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAuB9D,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;CAmB3E"}