boltstore 0.5.2 → 0.6.0

package/README.md

@@ -1,39 +1,81 @@
 # Boltstore
 
-**Single-binary, self-hosted Backend-as-a-Service.**
+**Boltstore** — A lightweight, self-hostable backend-as-a-service on SQLite + bun.js.
 
-Offline sync + S3-compatible storage + realtime + extensible JS hooks + Row-Level Security. Runs on a 512MB VPS. Built on **Bun**.
+Built for mobile apps that need offline sync, realtime updates, and managed authentication — without the complexity of managing a full cloud backend.
 
-Zero production dependencies. Everything uses Bun built-ins: `bun:sqlite`, `Bun.serve()`, `Bun.password`, Web Crypto API.
+## Features
+
+- **SQLite via HTTP REST API** — Full CRUD, filtering, sorting, pagination, aggregation, FTS5, JSON extraction, and raw SQL
+- **Multi-database support** — One instance serves multiple apps, each with isolated SQLite databases
+- **Realtime WebSocket** — Live subscriptions on collection and record changes
+- **Offline sync** — Client-side sync with conflict resolution (last-write-wins, custom merge)
+- **Authentication** — Email/password, JWT tokens, OAuth (future), Row-Level Security
+- **File storage** — Local filesystem and S3-compatible providers
+- **Hooks & extensions** — User-defined JavaScript functions for validation, auth, and business logic
+- **Admin panel** — Vue 3 SPA served at `/admin` with HMR during development
+- **Secure by design** — Route tiers (Public → Authenticated → Admin), parameterized queries, audit logging
 
-## Quick Start
+## Quick start
 
 ```bash
-bun install
-bun run dev
+npm install -g boltstore
+boltstore serve --port 8080 --db ./data
 ```
 
-## Packages
+Or with Docker:
 
-This repo is the main `boltstore` package (published on npm). The admin UI (Vue SPA) lives at `src/admin-ui/` and is built into the binary.
+```bash
+docker run -p 8080:8080 -v ./data:/data boltstore/boltstore
+```
 
-Companion packages published separately:
-- **[@boltstore/utils](https://www.npmjs.com/package/@boltstore/utils)** — Shared types, validation, filter parser (used by client SDK)
-- **[@boltstore/client](https://www.npmjs.com/package/@boltstore/client)** — TypeScript SDK for Bun, Node 18+, browsers
+## Configuration
 
-## Features
+CLI flags override env vars override config file:
+
+```bash
+boltstore serve --port 8080 --db ./data --config boltstore.yaml
+```
+
+| Environment variable | Default | Description |
+|---|---|---|
+| `PORT` | `8080` | HTTP server port |
+| `DATABASE_PATH` | `./data` | Directory for SQLite database files |
+| `JWT_SECRET` | — | Secret key for JWT tokens |
+| `RATE_LIMIT_PUBLIC` | `60/min` | Rate limit for public endpoints |
+| `RATE_LIMIT_AUTH` | `600/min` | Rate limit for authenticated endpoints |
+| `SERVER_TIMEZONE` | `UTC` | Server timezone |
+
+## API Tiers
+
+| Prefix | Access | Operations |
+|---|---|---|
+| `GET /api/health` | Public | Health check |
+| `POST /api/auth/*` | Public | Login, register |
+| `/api/collections/:collection/records` | Authenticated | CRUD on records |
+| `/api/admin/*` | Admin only | Schema changes, indexes, views, raw SQL, transactions |
 
-- SQLite with dual-pool concurrency and WAL mode
-- REST API auto-generated from collection schemas
-- JWT + bcrypt + OAuth2 (Google, GitHub) + API keys
-- Row-Level Security (SQL policy injection)
-- WebSocket pub/sub with RLS-aware fan-out
-- Offline sync (4 strategies, per-field override)
-- LocalDisk + S3-compatible file storage
-- Lifecycle hooks + custom routes/WS/CLI extensions
-- Vue admin UI embedded in binary
-- Standard SQLite backups + full-instance archives
+## Admin Panel
+
+Open `http://localhost:8080/admin` in your browser after starting the server.
+
+During development, Vite HMR automatically refreshes the admin UI as you edit Vue files.
+
+## Development
+
+```bash
+bun install
+bun run build    # compile TypeScript
+bun test         # run tests
+bun run dev      # watch mode
+```
+
+## Publishing
+
+```bash
+npm publish
+```
 
 ## License
 
-MIT
+MIT

package/dist/admin/api-keys.d.ts

@@ -0,0 +1,87 @@
+/**
+ * API Key management for Boltstore — machine-to-machine authentication.
+ *
+ * API keys provide scoped, non-expiring credentials for programmatic
+ * access. Keys are hashed before storage (bcrypt via Bun.password);
+ * the raw key is returned only once at creation time.
+ *
+ * Routes live under `/api/admin/api-keys` — admin only.
+ *
+ * @module boltstore/admin/api-keys
+ */
+import { DatabasePool } from "../db/pool";
+/** Valid operations an API key can be scoped to. */
+export declare const API_KEY_OPERATIONS: readonly ["read", "create", "update", "delete", "admin"];
+export type ApiKeyOperation = (typeof API_KEY_OPERATIONS)[number];
+/** Permission set attached to an API key. */
+export interface ApiKeyPermissions {
+    /** Allowed operations. An empty/missing list means no operations are allowed. */
+    operations?: ApiKeyOperation[];
+    /** Optional collection allow-list. If omitted, the key can access all collections. */
+    collections?: string[];
+}
+/** Internal representation of an API key row. */
+export interface ApiKey {
+    id: string;
+    name: string;
+    /** First 8 chars of the raw key for display (the full hash is stored internally). */
+    prefix: string;
+    permissions: ApiKeyPermissions;
+    /** Whether this key has been revoked. */
+    revoked: boolean;
+    /** ISO-8601 creation timestamp. */
+    created_at: string;
+    /** ISO-8601 timestamp of last use. Null if never used. */
+    last_used_at: string | null;
+}
+/** Full API key returned on creation (raw key + metadata). */
+export interface ApiKeyWithSecret extends ApiKey {
+    /** The raw API key secret. Only returned once at creation time. */
+    secret: string;
+}
+/** Verified API key context after successful authentication. */
+export interface ApiKeyContext {
+    keyId: string;
+    name: string;
+    permissions: ApiKeyPermissions;
+}
+/** Map an HTTP/CRUD intent to an API-key operation name. */
+export declare function operationForMethod(method: string): ApiKeyOperation;
+/** Check whether an API key context is allowed to perform an operation on a collection. */
+export declare function apiKeyAllows(ctx: ApiKeyContext, operation: ApiKeyOperation, collection?: string): boolean;
+/** Bootstrap the _api_keys table in a database. */
+export declare function bootstrapApiKeyTables(pool: DatabasePool): void;
+/**
+ * Create a new API key. Returns the raw key — store it immediately,
+ * as it will never be shown again.
+ *
+ * `POST /api/admin/:database/api-keys`
+ */
+export declare function createApiKey(pool: DatabasePool, name: string, permissions?: ApiKeyPermissions): Promise<ApiKeyWithSecret>;
+/**
+ * List all API keys for a database (without secrets).
+ *
+ * `GET /api/admin/:database/api-keys`
+ */
+export declare function listApiKeys(pool: DatabasePool): ApiKey[];
+/**
+ * Get a single API key by ID (without secret).
+ *
+ * `GET /api/admin/:database/api-keys/:id`
+ */
+export declare function getApiKey(pool: DatabasePool, id: string): ApiKey;
+/**
+ * Revoke an API key. After revocation, it can no longer be used for
+ * authentication. This is irreversible.
+ *
+ * `DELETE /api/admin/:database/api-keys/:id`
+ */
+export declare function revokeApiKey(pool: DatabasePool, id: string): void;
+/**
+ * Verify an API key secret and return the associated permissions context.
+ * Throws if the key is invalid, revoked, or not found.
+ *
+ * Used by the auth middleware to authenticate machine-to-machine requests.
+ */
+export declare function verifyApiKey(pool: DatabasePool, secret: string): Promise<ApiKeyContext>;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/admin/api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-keys.d.ts","sourceRoot":"","sources":["../../src/admin/api-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAQ1C,oDAAoD;AACpD,eAAO,MAAM,kBAAkB,0DAA2D,CAAC;AAC3F,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;IAC/B,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,iDAAiD;AACjD,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,iBAAiB,CAAC;IAC/B,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAiB,SAAQ,MAAM;IAC9C,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,iBAAiB,CAAC;CAChC;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAelE;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAC1B,GAAG,EAAE,aAAa,EAClB,SAAS,EAAE,eAAe,EAC1B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAST;AAYD,mDAAmD;AACnD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAmB9D;AA4BD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,iBAAsB,GAClC,OAAO,CAAC,gBAAgB,CAAC,CA2D3B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,EAAE,CAyBxD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CA6BhE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAejE;AAMD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC,CA6CxB"}

package/dist/admin/api-keys.js

@@ -0,0 +1,267 @@
+/**
+ * API Key management for Boltstore — machine-to-machine authentication.
+ *
+ * API keys provide scoped, non-expiring credentials for programmatic
+ * access. Keys are hashed before storage (bcrypt via Bun.password);
+ * the raw key is returned only once at creation time.
+ *
+ * Routes live under `/api/admin/api-keys` — admin only.
+ *
+ * @module boltstore/admin/api-keys
+ */
+import { hashPassword, verifyPassword } from "../auth";
+import { generateSecureId } from "@boltstore/utils";
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/** Valid operations an API key can be scoped to. */
+export const API_KEY_OPERATIONS = ["read", "create", "update", "delete", "admin"];
+/** Map an HTTP/CRUD intent to an API-key operation name. */
+export function operationForMethod(method) {
+    switch (method) {
+        case "GET":
+        case "HEAD":
+            return "read";
+        case "POST":
+            return "create";
+        case "PATCH":
+        case "PUT":
+            return "update";
+        case "DELETE":
+            return "delete";
+        default:
+            return "read";
+    }
+}
+/** Check whether an API key context is allowed to perform an operation on a collection. */
+export function apiKeyAllows(ctx, operation, collection) {
+    const ops = ctx.permissions.operations ?? [];
+    if (ops.includes("admin"))
+        return true;
+    if (!ops.includes(operation))
+        return false;
+    const cols = ctx.permissions.collections;
+    if (cols && cols.length > 0) {
+        if (!collection || !cols.includes(collection))
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const API_KEY_PREFIX = "blt_";
+// ---------------------------------------------------------------------------
+// Table bootstrapping
+// ---------------------------------------------------------------------------
+/** Bootstrap the _api_keys table in a database. */
+export function bootstrapApiKeyTables(pool) {
+    const db = pool.write();
+    db.run(`
+    CREATE TABLE IF NOT EXISTS _api_keys (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      key_hash TEXT NOT NULL UNIQUE,
+      prefix TEXT NOT NULL,
+      permissions_json TEXT NOT NULL DEFAULT '{}',
+      revoked INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL,
+      last_used_at TEXT
+    )
+  `);
+    db.run(`
+    CREATE INDEX IF NOT EXISTS idx_api_keys_prefix ON _api_keys(prefix)
+  `);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Generate a unique API key ID. */
+function generateKeyId() {
+    return generateSecureId("apk");
+}
+/** Generate a cryptographically random API key secret. */
+function generateKeySecret() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    const raw = Buffer.from(bytes).toString("base64url");
+    return `${API_KEY_PREFIX}${raw}`;
+}
+/** Get current ISO-8601 timestamp. */
+function now() {
+    return new Date().toISOString();
+}
+// ---------------------------------------------------------------------------
+// Public API — CRUD
+// ---------------------------------------------------------------------------
+/**
+ * Create a new API key. Returns the raw key — store it immediately,
+ * as it will never be shown again.
+ *
+ * `POST /api/admin/:database/api-keys`
+ */
+export async function createApiKey(pool, name, permissions = {}) {
+    if (!name || typeof name !== "string" || name.trim().length === 0) {
+        throw Object.assign(new Error("API key name is required."), { status: 400 });
+    }
+    if (name.length > 128) {
+        throw Object.assign(new Error("API key name must be 128 characters or fewer."), { status: 400 });
+    }
+    // Validate permissions
+    if (permissions.collections) {
+        if (!Array.isArray(permissions.collections)) {
+            throw Object.assign(new Error("permissions.collections must be an array."), { status: 400 });
+        }
+        for (const c of permissions.collections) {
+            if (typeof c !== "string") {
+                throw Object.assign(new Error("permissions.collections entries must be strings."), { status: 400 });
+            }
+        }
+    }
+    if (permissions.operations) {
+        if (!Array.isArray(permissions.operations)) {
+            throw Object.assign(new Error("permissions.operations must be an array."), { status: 400 });
+        }
+        for (const op of permissions.operations) {
+            if (typeof op !== "string" || !API_KEY_OPERATIONS.includes(op)) {
+                throw Object.assign(new Error(`Invalid operation "${op}". Valid operations: ${API_KEY_OPERATIONS.join(", ")}.`), { status: 400 });
+            }
+        }
+    }
+    bootstrapApiKeyTables(pool);
+    const secret = generateKeySecret();
+    const keyHash = await hashPassword(secret);
+    const id = generateKeyId();
+    const prefix = secret.slice(0, 8);
+    const ts = now();
+    const db = pool.write();
+    db.run(`INSERT INTO _api_keys (id, name, key_hash, prefix, permissions_json, revoked, created_at, last_used_at)
+     VALUES (?, ?, ?, ?, ?, 0, ?, NULL)`, [id, name.trim(), keyHash, prefix, JSON.stringify(permissions), ts]);
+    return {
+        id,
+        name: name.trim(),
+        prefix,
+        secret,
+        permissions,
+        revoked: false,
+        created_at: ts,
+        last_used_at: null,
+    };
+}
+/**
+ * List all API keys for a database (without secrets).
+ *
+ * `GET /api/admin/:database/api-keys`
+ */
+export function listApiKeys(pool) {
+    bootstrapApiKeyTables(pool);
+    const db = pool.read();
+    const rows = db
+        .query("SELECT id, name, prefix, permissions_json, revoked, created_at, last_used_at FROM _api_keys ORDER BY created_at DESC")
+        .all();
+    return rows.map((row) => ({
+        id: row.id,
+        name: row.name,
+        prefix: row.prefix,
+        permissions: safeParseJson(row.permissions_json),
+        revoked: row.revoked === 1,
+        created_at: row.created_at,
+        last_used_at: row.last_used_at,
+    }));
+}
+/**
+ * Get a single API key by ID (without secret).
+ *
+ * `GET /api/admin/:database/api-keys/:id`
+ */
+export function getApiKey(pool, id) {
+    bootstrapApiKeyTables(pool);
+    const db = pool.read();
+    const row = db
+        .query("SELECT id, name, prefix, permissions_json, revoked, created_at, last_used_at FROM _api_keys WHERE id=?")
+        .get(id);
+    if (!row) {
+        throw Object.assign(new Error(`API key "${id}" not found.`), { status: 404 });
+    }
+    return {
+        id: row.id,
+        name: row.name,
+        prefix: row.prefix,
+        permissions: safeParseJson(row.permissions_json),
+        revoked: row.revoked === 1,
+        created_at: row.created_at,
+        last_used_at: row.last_used_at,
+    };
+}
+/**
+ * Revoke an API key. After revocation, it can no longer be used for
+ * authentication. This is irreversible.
+ *
+ * `DELETE /api/admin/:database/api-keys/:id`
+ */
+export function revokeApiKey(pool, id) {
+    bootstrapApiKeyTables(pool);
+    const db = pool.write();
+    // Verify the key exists
+    const existing = db
+        .query("SELECT id FROM _api_keys WHERE id=?")
+        .get(id);
+    if (!existing) {
+        throw Object.assign(new Error(`API key "${id}" not found.`), { status: 404 });
+    }
+    db.run("UPDATE _api_keys SET revoked=1 WHERE id=?", [id]);
+}
+// ---------------------------------------------------------------------------
+// Authentication
+// ---------------------------------------------------------------------------
+/**
+ * Verify an API key secret and return the associated permissions context.
+ * Throws if the key is invalid, revoked, or not found.
+ *
+ * Used by the auth middleware to authenticate machine-to-machine requests.
+ */
+export async function verifyApiKey(pool, secret) {
+    if (!secret || typeof secret !== "string" || secret.length < 4) {
+        throw Object.assign(new Error("Invalid API key."), { status: 401 });
+    }
+    bootstrapApiKeyTables(pool);
+    // Look up by prefix first (efficient index scan)
+    const prefix = secret.slice(0, 8);
+    const db = pool.read();
+    const candidates = db
+        .query("SELECT id, name, key_hash, permissions_json, revoked FROM _api_keys WHERE prefix=? AND revoked=0")
+        .all(prefix);
+    for (const candidate of candidates) {
+        const match = await verifyPassword(secret, candidate.key_hash);
+        if (match) {
+            // Update last_used_at
+            try {
+                pool.write().run("UPDATE _api_keys SET last_used_at=? WHERE id=?", [
+                    now(),
+                    candidate.id,
+                ]);
+            }
+            catch {
+                // Non-critical — don't fail auth for a tracking update
+            }
+            return {
+                keyId: candidate.id,
+                name: candidate.name,
+                permissions: safeParseJson(candidate.permissions_json),
+            };
+        }
+    }
+    throw Object.assign(new Error("Invalid or revoked API key."), { status: 401 });
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function safeParseJson(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=api-keys.js.map

package/dist/admin/api-keys.js.map

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

package/dist/admin/backup.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Backup & Restore module for Boltstore databases.
+ *
+ * Creates SQLite backup snapshots via `VACUUM INTO` and supports
+ * restoring from those snapshots. Restore closes the existing pool
+ * (dropping all connections), swaps the database file, and reopens.
+ *
+ * @module boltstore/admin/backup
+ */
+import { DatabasePool } from "../db/pool";
+import { DatabaseManager } from "../db/manager";
+export interface BackupOptions {
+    /** Human-readable label for this backup. */
+    label?: string;
+}
+export interface BackupInfo {
+    /** Unique backup identifier (generated). */
+    id: string;
+    /** Full filesystem path to the backup file. */
+    path: string;
+    /** Size of the backup file in bytes. */
+    sizeBytes: number;
+    /** ISO-8601 timestamp of when the backup was created. */
+    createdAt: string;
+    /** Optional human-readable label. */
+    label?: string;
+}
+export interface RestoreResult {
+    /** Database name that was restored. */
+    database: string;
+    /** Path to the backup file that was used. */
+    backupPath: string;
+    /** ISO-8601 timestamp of when the restore occurred. */
+    restoredAt: string;
+}
+/**
+ * Create a backup of a database using SQLite's `VACUUM INTO`.
+ *
+ * The backup is a self-contained, consistent SQLite snapshot stored in
+ * `data/{app}/backups/{app}-{timestamp}.db`. Metadata is recorded in the
+ * `_backups` table for later listing and restore.
+ *
+ * `POST /api/admin/:database/backup`
+ */
+export declare function createBackup(pool: DatabasePool, databaseName: string, dataDir: string, options?: BackupOptions): BackupInfo;
+/**
+ * List all backups for a database.
+ *
+ * `GET /api/admin/:database/backups`
+ */
+export declare function listBackups(pool: DatabasePool): BackupInfo[];
+/**
+ * Get a specific backup by ID.
+ */
+export declare function getBackup(pool: DatabasePool, backupId: string): BackupInfo;
+/**
+ * Restore a database from a backup snapshot.
+ *
+ * **This closes the existing connection pool**, swaps the database file
+ * with the backup, then reopens the pool. All active connections to the
+ * database will be dropped — suitable for maintenance windows.
+ *
+ * After restore, the `_backups` metadata table persists because it lives
+ * inside the backup snapshot itself.
+ *
+ * `POST /api/admin/:database/restore/:backupId`
+ */
+export declare function restoreBackup(manager: DatabaseManager, databaseName: string, backupId: string): RestoreResult;
+/**
+ * Restore a database directly from a file path (CLI usage).
+ *
+ * Useful when the backup file is not tracked in `_backups` metadata,
+ * e.g., a backup copied from another machine.
+ */
+export declare function restoreFromFile(manager: DatabaseManager, databaseName: string, backupFilePath: string): RestoreResult;
+//# sourceMappingURL=backup.d.ts.map

package/dist/admin/backup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/admin/backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAoBhD,MAAM,WAAW,aAAa;IAC5B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;CACpB;AA0DD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,YAAY,EAClB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,UAAU,CA8CZ;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,EAAE,CA0B5D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAgC1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,aAAa,CA+Cf;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,GACrB,aAAa,CAmDf"}