sovr-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOVR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,341 @@
+# SOVR MCP Server
+
+> **SOVR MCP Server turns any AI agent into a governed executor: no irreversible action without a verifiable permit, audit trail, and evidence bundle.**
+
+## Overview
+
+SOVR MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/) server that provides a **Responsibility Layer** for AI agents. It intercepts irreversible operations and ensures:
+
+- **Gate Check**: Every action is evaluated against policies before execution
+- **Approval Workflow**: High-risk operations require human approval
+- **Verifiable Permits**: Signed, time-limited execution credentials
+- **Audit Trail**: Immutable evidence chain for compliance
+
+## Installation
+
+```bash
+# Via npx (recommended)
+npx sovr-mcp-server
+
+# Or install globally
+npm install -g sovr-mcp-server
+sovr-mcp-server
+```
+
+## Configuration
+
+Set the following environment variables:
+
+```bash
+# Required (unless using local mode)
+export SOVR_API_KEY="sovr_sk_your_tenant_id_your_key"
+
+# Optional
+export SOVR_API_URL="https://api.sovr.inc"  # Default API endpoint
+export SOVR_SIGNING_KEY="your_ed25519_private_key_hex"  # For production
+export SOVR_LOCAL_MODE="true"  # Enable local mode (no API required)
+```
+
+### Local Development Mode
+
+For testing without a remote API, enable local mode:
+
+```json
+{
+  "mcpServers": {
+    "sovr": {
+      "command": "npx",
+      "args": ["sovr-mcp-server"],
+      "env": {
+        "SOVR_LOCAL_MODE": "true"
+      }
+    }
+  }
+}
+```
+
+Local mode provides:
+- In-memory policy engine with default rules
+- Full gate_check, approval, permit, and receipt workflow
+- Additional tools: `kill_switch`, `audit_query`, `policy_list`
+
+## Claude Desktop Integration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "sovr": {
+      "command": "npx",
+      "args": ["sovr-mcp-server"],
+      "env": {
+        "SOVR_API_KEY": "sovr_sk_your_tenant_id_your_key"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `gate_check`
+
+Evaluate if an irreversible action should be allowed.
+
+**Input:**
+```json
+{
+  "action": "delete_database",
+  "resource": "production/users",
+  "context": { "reason": "cleanup" }
+}
+```
+
+**Output:**
+```json
+{
+  "decision_id": "dec_abc123",
+  "allowed": true,
+  "requires_approval": false,
+  "reason": "Action matches allowed policy",
+  "risk_score": 45,
+  "value_score": 80,
+  "policy_version": "v1.2.0"
+}
+```
+
+### `request_approval`
+
+Request human approval for high-risk operations.
+
+**Input:**
+```json
+{
+  "decision_id": "dec_abc123",
+  "justification": "Need to delete test data before production release",
+  "urgency": "high"
+}
+```
+
+**Output:**
+```json
+{
+  "approval_id": "apr_xyz789",
+  "status": "pending",
+  "approval_url": "https://sovr.inc/approve/apr_xyz789",
+  "estimated_wait_seconds": 300,
+  "expires_at": 1706745600
+}
+```
+
+### `grant_permit`
+
+Issue a cryptographically signed execution permit.
+
+**Input:**
+```json
+{
+  "decision_id": "dec_abc123",
+  "ttl_seconds": 300
+}
+```
+
+**Output:**
+```json
+{
+  "permit_id": "permit_def456",
+  "jti": "unique_token_id",
+  "decision_id": "dec_abc123",
+  "expires_at": 1706745900,
+  "signature": "ed25519_signature_hex",
+  "public_key": "ed25519_public_key_hex"
+}
+```
+
+### `submit_receipt`
+
+Record execution evidence to complete the audit trail.
+
+### `system_status`
+
+Check system health and kill switch state.
+
+**Output:**
+```json
+{
+  "healthy": true,
+  "kill_switch_active": false,
+  "api_version": "v1.0.0",
+  "policy_version": "v1.2.0"
+}
+```
+
+### Local Mode Tools
+
+#### `kill_switch`
+
+Emergency stop mechanism (local mode only).
+
+**Input:**
+```json
+{
+  "action": "activate",
+  "reason": "Security incident detected",
+  "confirmation": "CONFIRM_KILL_SWITCH"
+}
+```
+
+#### `audit_query`
+
+Query the audit trail (local mode only).
+
+**Input:**
+```json
+{
+  "decision_id": "dec_abc123",
+  "limit": 20
+}
+```
+
+#### `policy_list`
+
+View policy configurations (local mode only).
+
+**Input:**
+```json
+{
+  "active_only": true,
+  "include_rules": true
+}
+```
+
+**Input:**
+```json
+{
+  "decision_id": "dec_abc123",
+  "permit_id": "permit_def456",
+  "external_ref": "job_12345",
+  "status": "success",
+  "started_at": 1706745600,
+  "finished_at": 1706745650,
+  "output_hash": "sha512_hash_of_output",
+  "artifact_refs": ["s3://bucket/logs/job_12345.log"],
+  "idempotency_key": "unique_receipt_key"
+}
+```
+
+**Output:**
+```json
+{
+  "receipt_id": "rcpt_ghi789",
+  "trust_hash": "sha512_trust_chain_hash",
+  "evidence_hash": "sha512_evidence_hash",
+  "chain_position": 42,
+  "recorded_at": 1706745660
+}
+```
+
+## Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        AI Agent                                  │
+│                                                                  │
+│  1. "I want to delete the production database"                  │
+│                           │                                      │
+│                           ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                    gate_check                                ││
+│  │  action: "delete_database"                                   ││
+│  │  resource: "production/users"                                ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                           │                                      │
+│                           ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │              Decision: requires_approval                     ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                           │                                      │
+│                           ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                 request_approval                             ││
+│  │  justification: "Cleanup before release"                     ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                           │                                      │
+│                           ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │              Human approves via URL                          ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                           │                                      │
+│                           ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                  grant_permit                                ││
+│  │  → Signed permit (Ed25519, TTL: 5min)                       ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                           │                                      │
+│                           ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                 Execute Action                               ││
+│  │  (Agent performs the actual deletion)                        ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                           │                                      │
+│                           ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │                 submit_receipt                               ││
+│  │  → Evidence recorded to audit chain                          ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## API Key Scopes
+
+| Scope | Description | Default |
+|-------|-------------|---------|
+| `gate:check` | Call gate_check | ✅ |
+| `receipt:submit` | Submit execution receipts | ✅ |
+| `permit:grant` | Grant execution permits | Admin only |
+| `approval:request` | Request human approval | Admin only |
+| `audit:read` | Read audit logs | Admin only |
+| `status:read` | Read system status | Admin only |
+
+## Security
+
+- **Ed25519 Signatures**: Permits are cryptographically signed
+- **Time-Limited Permits**: Default 5 minutes, configurable 60-900 seconds
+- **Audit Trail**: All operations are logged with trace IDs
+- **Rate Limiting**: Per-key rate limits enforced
+
+## Pricing
+
+| Metric | Description |
+|--------|-------------|
+| `irreversible.allowed` | Primary billing metric |
+| `trust_bundle.exported` | Trust evidence packages |
+| `approval.requested` | Human approval workflows |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Build
+pnpm build
+
+# Run locally
+SOVR_API_KEY=sovr_sk_test_key pnpm dev
+```
+
+## License
+
+MIT
+
+## Links
+
+- [SOVR Website](https://sovr.inc)
+- [Documentation](https://docs.sovr.inc)
+- [MCP Protocol](https://modelcontextprotocol.io/)

package/dist/api/client.d.ts

@@ -0,0 +1,59 @@
+/**
+ * SOVR API Client
+ *
+ * Communicates with the SOVR backend (https://api.sovr.inc)
+ * All MCP tools delegate to this client for actual operations.
+ */
+import type { GateCheckInput, GateCheckResult, RequestApprovalInput, ApprovalResult, SubmitReceiptInput, ReceiptResult, SystemStatus, ApiKey } from '../types/index.js';
+export interface SovrClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+}
+export declare class SovrApiClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(config: SovrClientConfig);
+    /**
+     * Gate Check - Evaluate if an action should be allowed
+     */
+    gateCheck(input: GateCheckInput): Promise<GateCheckResult>;
+    /**
+     * Request Approval - Initiate human approval workflow
+     */
+    requestApproval(input: RequestApprovalInput): Promise<ApprovalResult>;
+    /**
+     * Get Approval Status
+     */
+    getApprovalStatus(approvalId: string): Promise<ApprovalResult>;
+    /**
+     * Submit Receipt - Record execution evidence
+     */
+    submitReceipt(input: SubmitReceiptInput): Promise<ReceiptResult>;
+    /**
+     * Get System Status
+     */
+    getSystemStatus(): Promise<SystemStatus>;
+    /**
+     * Validate API Key and get key info
+     */
+    validateApiKey(): Promise<ApiKey>;
+    /**
+     * Get Decision Details
+     */
+    getDecision(decisionId: string): Promise<GateCheckResult & {
+        approval?: ApprovalResult;
+        permit_granted?: boolean;
+    }>;
+    private request;
+}
+export declare class SovrApiError extends Error {
+    status: number;
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+export declare function createClient(config: SovrClientConfig): SovrApiClient;
+export declare function getClient(): SovrApiClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,MAAM,EAEP,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,gBAAgB;IAepC;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAOhE;;OAEG;IACG,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAO3E;;OAEG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAMpE;;OAEG;IACG,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;IAOtE;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC;IAM9C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAMvC;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG;QAC/D,QAAQ,CAAC,EAAE,cAAc,CAAC;QAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;YAUY,OAAO;CAwDtB;AAMD,qBAAa,YAAa,SAAQ,KAAK;IAE5B,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,MAAM;IAEZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAHjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAK3C;AAgBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAGpE;AAED,wBAAgB,SAAS,IAAI,aAAa,CAKzC"}

package/dist/api/client.js

@@ -0,0 +1,162 @@
+/**
+ * SOVR API Client
+ *
+ * Communicates with the SOVR backend (https://api.sovr.inc)
+ * All MCP tools delegate to this client for actual operations.
+ */
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+const MAX_RETRIES = 3;
+const RETRY_DELAY = 1000; // 1 second
+export class SovrApiClient {
+    baseUrl;
+    apiKey;
+    timeout;
+    constructor(config) {
+        // Support env var override for API URL
+        this.baseUrl = (config.baseUrl || process.env.SOVR_API_URL || 'https://api.sovr.inc').replace(/\/$/, '');
+        this.apiKey = config.apiKey;
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+        // Log connection info (without exposing full API key)
+        const keyPreview = this.apiKey.slice(0, 15) + '...';
+        console.error(`[SOVR API] Connecting to ${this.baseUrl} with key ${keyPreview}`);
+    }
+    // ==========================================================================
+    // Core API Methods
+    // ==========================================================================
+    /**
+     * Gate Check - Evaluate if an action should be allowed
+     */
+    async gateCheck(input) {
+        return this.request('/api/mcp/gate-check', {
+            method: 'POST',
+            body: input,
+        });
+    }
+    /**
+     * Request Approval - Initiate human approval workflow
+     */
+    async requestApproval(input) {
+        return this.request('/api/mcp/request-approval', {
+            method: 'POST',
+            body: input,
+        });
+    }
+    /**
+     * Get Approval Status
+     */
+    async getApprovalStatus(approvalId) {
+        return this.request(`/api/mcp/approval/${approvalId}`, {
+            method: 'GET',
+        });
+    }
+    /**
+     * Submit Receipt - Record execution evidence
+     */
+    async submitReceipt(input) {
+        return this.request('/api/mcp/submit-receipt', {
+            method: 'POST',
+            body: input,
+        });
+    }
+    /**
+     * Get System Status
+     */
+    async getSystemStatus() {
+        return this.request('/api/mcp/status', {
+            method: 'GET',
+        });
+    }
+    /**
+     * Validate API Key and get key info
+     */
+    async validateApiKey() {
+        return this.request('/api/mcp/validate-key', {
+            method: 'GET',
+        });
+    }
+    /**
+     * Get Decision Details
+     */
+    async getDecision(decisionId) {
+        return this.request(`/api/mcp/decision/${decisionId}`, {
+            method: 'GET',
+        });
+    }
+    // ==========================================================================
+    // Internal Request Handler
+    // ==========================================================================
+    async request(path, options) {
+        const url = `${this.baseUrl}${path}`;
+        let lastError = null;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            try {
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                const response = await fetch(url, {
+                    method: options.method,
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${this.apiKey}`,
+                        'X-SOVR-Client': 'sovr-mcp-server/0.1.0',
+                    },
+                    body: options.body ? JSON.stringify(options.body) : undefined,
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    const errorBody = await response.json().catch(() => ({}));
+                    throw new SovrApiError(response.status, String(errorBody.code || 'API_ERROR'), String(errorBody.message || `HTTP ${response.status}`), errorBody.details);
+                }
+                return await response.json();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on client errors (4xx)
+                if (error instanceof SovrApiError && error.status >= 400 && error.status < 500) {
+                    throw error;
+                }
+                // Wait before retry (exponential backoff)
+                if (attempt < MAX_RETRIES - 1) {
+                    await sleep(RETRY_DELAY * Math.pow(2, attempt));
+                }
+            }
+        }
+        throw lastError || new Error('Request failed after retries');
+    }
+}
+// ==========================================================================
+// Error Class
+// ==========================================================================
+export class SovrApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = 'SovrApiError';
+    }
+}
+// ==========================================================================
+// Utilities
+// ==========================================================================
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// ==========================================================================
+// Factory
+// ==========================================================================
+let clientInstance = null;
+export function createClient(config) {
+    clientInstance = new SovrApiClient(config);
+    return clientInstance;
+}
+export function getClient() {
+    if (!clientInstance) {
+        throw new Error('SOVR API client not initialized. Call createClient() first.');
+    }
+    return clientInstance;
+}
+//# sourceMappingURL=client.js.map

package/dist/api/client.js.map

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

package/dist/auth/apiKey.d.ts

@@ -0,0 +1,53 @@
+/**
+ * API Key Authentication Module
+ *
+ * Validates API keys and enforces scopes/rate limits.
+ * All key usage is automatically audited.
+ */
+import type { Scope, AuditEvent } from '../types/index.js';
+/**
+ * API Key format: sovr_sk_<tenant_id>_<random>
+ * Example: sovr_sk_tenant123_abc123xyz789
+ */
+export declare function parseApiKey(key: string): {
+    tenantId: string;
+    keyId: string;
+} | null;
+/**
+ * Generate a new API key
+ */
+export declare function generateApiKey(tenantId: string): string;
+export declare const DEFAULT_SCOPES: Scope[];
+export declare const ADMIN_SCOPES: Scope[];
+export declare function hasRequiredScopes(keyScopes: Scope[], toolName: string): boolean;
+export declare function getMissingScopes(keyScopes: Scope[], toolName: string): Scope[];
+export declare function checkRateLimit(keyId: string, limit: number): {
+    allowed: boolean;
+    remaining: number;
+    resetAt: number;
+};
+export declare function logAuditEvent(event: Omit<AuditEvent, 'event_id' | 'timestamp'>): AuditEvent;
+export declare function getRecentAuditEvents(limit?: number): AuditEvent[];
+export interface AuthContext {
+    keyId: string;
+    tenantId: string;
+    scopes: Scope[];
+    rateLimit: number;
+    traceId: string;
+}
+/**
+ * Validate API key and return auth context
+ * In production, this would call the SOVR API to validate
+ */
+export declare function validateApiKey(apiKey: string): Promise<AuthContext | null>;
+/**
+ * Authenticate and authorize a tool call
+ */
+export declare function authenticateToolCall(apiKey: string, toolName: string): Promise<{
+    success: true;
+    context: AuthContext;
+} | {
+    success: false;
+    error: string;
+}>;
+//# sourceMappingURL=apiKey.d.ts.map

package/dist/auth/apiKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiKey.d.ts","sourceRoot":"","sources":["../../src/auth/apiKey.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAU,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAMnE;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAOnF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGvD;AAMD,eAAO,MAAM,cAAc,EAAE,KAAK,EAAqC,CAAC;AACxE,eAAO,MAAM,YAAY,EAAE,KAAK,EAAsG,CAAC;AAevI,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAI/E;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,EAAE,CAI9E;AAcD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiBrH;AASD,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,WAAW,CAAC,GAAG,UAAU,CAkB3F;AAED,wBAAgB,oBAAoB,CAAC,KAAK,GAAE,MAAY,GAAG,UAAU,EAAE,CAEtE;AAMD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAahF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BtF"}