@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/protocol/DIDResolver.js

@@ -0,0 +1,495 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIDResolver = void 0;
+const ethers_1 = require("ethers");
+// NOTE: These imports require npm packages to be installed:
+// - did-resolver
+// - ethr-did-resolver
+const did_resolver_1 = require("did-resolver");
+const ethr_did_resolver_1 = require("ethr-did-resolver");
+const networks_1 = require("../config/networks");
+const errors_1 = require("../errors");
+/**
+ * DIDResolver - Resolve DIDs to DID Documents (AIP-7 §2.2)
+ *
+ * Uses ethr-did-resolver library for resolution against AGIRAILS Identity Registry.
+ * Supports did:ethr method with explicit chainId format: did:ethr:<chainId>:<address>
+ *
+ * @example
+ * ```typescript
+ * const resolver = await DIDResolver.create({ network: 'base-sepolia' });
+ *
+ * // Resolve DID to DID Document
+ * const result = await resolver.resolve('did:ethr:84532:0x742d35cc6634c0532925a3b844bc9e7595f0beb');
+ * console.log(result.didDocument);
+ *
+ * // Verify signature
+ * const isValid = await resolver.verifySignature(
+ *   'did:ethr:84532:0x742d35cc...',
+ *   'Hello AGIRAILS',
+ *   '0x1234...',
+ *   { chainId: 84532 }
+ * );
+ * ```
+ *
+ * @security
+ * - Always validates DID format before resolution
+ * - Checks chainId matches expected network
+ * - Verifies signatures using ethers.js verifyMessage
+ * - Prevents cross-chain replay attacks via chainId validation
+ */
+class DIDResolver {
+    /**
+     * Private constructor - use DIDResolver.create() factory method
+     */
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Factory method to create DIDResolver instance
+     *
+     * @param config - Configuration options
+     * @returns Configured DIDResolver instance
+     * @throws ValidationError if configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * // Using predefined network
+     * const resolver = await DIDResolver.create({ network: 'base-sepolia' });
+     *
+     * // Using custom RPC and registry
+     * const resolver = await DIDResolver.create({
+     *   chainId: 84532,
+     *   rpcUrl: 'https://sepolia.base.org',
+     *   registryAddress: '0x...'
+     * });
+     * ```
+     */
+    static async create(config = {}) {
+        // Resolve configuration with defaults
+        const resolvedConfig = DIDResolver.resolveConfig(config);
+        // Validate configuration
+        DIDResolver.validateConfig(resolvedConfig);
+        // Initialize did-resolver with ethr-did-resolver
+        const providerConfig = {
+            networks: [
+                {
+                    name: resolvedConfig.network || `chain-${resolvedConfig.chainId}`,
+                    chainId: `0x${resolvedConfig.chainId.toString(16)}`,
+                    rpcUrl: resolvedConfig.rpcUrl,
+                    registry: resolvedConfig.registryAddress
+                }
+            ]
+        };
+        const ethrResolver = (0, ethr_did_resolver_1.getResolver)(providerConfig);
+        const resolver = new did_resolver_1.Resolver(ethrResolver);
+        const instance = new DIDResolver(resolvedConfig);
+        instance.resolver = resolver;
+        return instance;
+    }
+    /**
+     * Resolve configuration with defaults from network config
+     */
+    static resolveConfig(config) {
+        // If network specified, use network defaults
+        if (config.network) {
+            const networkConfig = (0, networks_1.getNetwork)(config.network);
+            return {
+                network: config.network,
+                chainId: config.chainId || networkConfig.chainId,
+                rpcUrl: config.rpcUrl || networkConfig.rpcUrl,
+                registryAddress: config.registryAddress || networkConfig.contracts.agentRegistry || ''
+            };
+        }
+        // Custom configuration (must provide all required fields)
+        if (!config.chainId || !config.rpcUrl) {
+            throw new errors_1.ValidationError('config', 'Must provide either network name or (chainId + rpcUrl)');
+        }
+        return {
+            network: config.network || '',
+            chainId: config.chainId,
+            rpcUrl: config.rpcUrl,
+            registryAddress: config.registryAddress || ''
+        };
+    }
+    /**
+     * Validate configuration
+     */
+    static validateConfig(config) {
+        if (!config.chainId || config.chainId <= 0) {
+            throw new errors_1.ValidationError('chainId', 'Invalid chainId');
+        }
+        if (!config.rpcUrl || !config.rpcUrl.startsWith('http')) {
+            throw new errors_1.ValidationError('rpcUrl', 'Invalid RPC URL');
+        }
+        // Registry address is optional (will use default if not provided)
+        // But if provided, must be valid address
+        if (config.registryAddress) {
+            try {
+                (0, ethers_1.getAddress)(config.registryAddress);
+            }
+            catch (error) {
+                throw new errors_1.ValidationError('registryAddress', 'Invalid registry address');
+            }
+        }
+    }
+    /**
+     * Get resolver configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Resolve DID to DID Document
+     *
+     * @param did - DID to resolve (format: did:ethr:<chainId>:<address>)
+     * @returns DID resolution result with document and metadata
+     * @throws ValidationError if DID format is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await resolver.resolve('did:ethr:84532:0x742d35cc6634c0532925a3b844bc9e7595f0beb');
+     *
+     * if (result.didDocument) {
+     *   console.log('Identity owner:', result.didDocument.verificationMethod[0].controller);
+     *   console.log('Service endpoints:', result.didDocument.service);
+     * } else {
+     *   console.error('Resolution failed:', result.didResolutionMetadata.error);
+     * }
+     * ```
+     */
+    async resolve(did) {
+        // Validate DID format
+        const parsed = DIDResolver.parseDID(did);
+        // Check chainId matches expected network
+        if (parsed.chainId !== this.config.chainId) {
+            return {
+                didDocument: null,
+                didResolutionMetadata: {
+                    error: 'invalidDid',
+                    message: `DID chainId ${parsed.chainId} does not match resolver chainId ${this.config.chainId}`
+                },
+                didDocumentMetadata: {}
+            };
+        }
+        // Perform resolution using did-resolver
+        const result = await this.resolver.resolve(did);
+        return result;
+    }
+    /**
+     * Verify a signature was made by DID controller or authorized delegate
+     *
+     * @param did - DID of expected signer
+     * @param message - Original message that was signed
+     * @param signature - Signature to verify (0x-prefixed hex string)
+     * @param options - Verification options (chainId validation, domain separation, etc.)
+     * @returns Verification result with validity and signer info
+     *
+     * @security
+     * - Validates chainId to prevent cross-chain replay attacks
+     * - Uses domain separation to prevent cross-protocol replay attacks (MEDIUM finding fix)
+     * - Resolves DID to get current owner and delegates
+     * - Checks if signer is owner or valid delegate (MEDIUM finding fix)
+     * - Validates delegate expiration timestamps if provided
+     *
+     * @example
+     * ```typescript
+     * // With domain separation (recommended - default)
+     * const result = await resolver.verifySignature(
+     *   'did:ethr:84532:0x742d35cc...',
+     *   'Hello AGIRAILS',
+     *   '0x1234...',
+     *   { chainId: 84532, useDomainSeparation: true }
+     * );
+     *
+     * // Without domain separation (backwards compatibility only)
+     * const legacyResult = await resolver.verifySignature(
+     *   'did:ethr:84532:0x742d35cc...',
+     *   'Hello AGIRAILS',
+     *   '0x1234...',
+     *   { chainId: 84532, useDomainSeparation: false }
+     * );
+     *
+     * if (result.valid) {
+     *   console.log('Signature is valid!');
+     *   console.log('Signer:', result.signer);
+     *   console.log('Is delegate:', result.isDelegate);
+     *   if (result.isDelegate) {
+     *     console.log('Delegate type:', result.delegateType);
+     *   }
+     * } else {
+     *   console.error('Invalid signature:', result.error);
+     * }
+     * ```
+     */
+    async verifySignature(did, message, signature, options) {
+        try {
+            // Validate DID format
+            const parsed = DIDResolver.parseDID(did);
+            // Validate chainId matches
+            if (parsed.chainId !== options.chainId) {
+                return {
+                    valid: false,
+                    error: `DID chainId ${parsed.chainId} does not match expected chainId ${options.chainId}`
+                };
+            }
+            // SECURITY FIX (MEDIUM): Domain separation to prevent cross-protocol replay attacks
+            // Default to true for security, but allow opt-out for backwards compatibility
+            const useDomainSeparation = options.useDomainSeparation !== false;
+            const messageToVerify = useDomainSeparation
+                ? this.createDomainSeparatedMessage(message, parsed.chainId, did)
+                : message;
+            // Recover signer from signature
+            const recoveredAddress = (0, ethers_1.verifyMessage)(messageToVerify, signature);
+            const signerLower = recoveredAddress.toLowerCase();
+            const didAddressLower = parsed.address.toLowerCase();
+            // Check if signer is the DID address itself (owner)
+            if (signerLower === didAddressLower) {
+                return {
+                    valid: true,
+                    signer: recoveredAddress,
+                    isDelegate: false
+                };
+            }
+            // SECURITY FIX (MEDIUM): Implement delegate validation
+            // Check if signer is a valid delegate in the DID Document
+            const resolution = await this.resolve(did);
+            if (resolution.didDocument && resolution.didDocument.authentication) {
+                // Iterate through authentication methods to find valid delegates
+                for (const auth of resolution.didDocument.authentication) {
+                    // auth can be a string (reference to verificationMethod) or VerificationMethod object
+                    const verificationMethod = typeof auth === 'string'
+                        ? resolution.didDocument.verificationMethod?.find(vm => vm.id === auth)
+                        : auth;
+                    if (verificationMethod) {
+                        // Extract delegate address from verification method
+                        const delegateAddress = this.extractAddressFromVerificationMethod(verificationMethod);
+                        if (delegateAddress && delegateAddress.toLowerCase() === signerLower) {
+                            // Check delegate validity if timestamp provided
+                            if (options.timestamp && verificationMethod.validTo) {
+                                const validToTimestamp = typeof verificationMethod.validTo === 'bigint'
+                                    ? Number(verificationMethod.validTo)
+                                    : verificationMethod.validTo;
+                                if (options.timestamp > validToTimestamp) {
+                                    return {
+                                        valid: false,
+                                        signer: recoveredAddress,
+                                        error: 'Delegate expired'
+                                    };
+                                }
+                            }
+                            return {
+                                valid: true,
+                                signer: recoveredAddress,
+                                isDelegate: true,
+                                delegateType: verificationMethod.type
+                            };
+                        }
+                    }
+                }
+            }
+            // Signer is neither owner nor valid delegate
+            return {
+                valid: false,
+                signer: recoveredAddress,
+                error: 'Signer is not the DID controller or a valid delegate'
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                error: error instanceof Error ? error.message : 'Signature verification failed'
+            };
+        }
+    }
+    /**
+     * Build DID from address and chainId
+     *
+     * @param address - Ethereum address (with or without 0x prefix)
+     * @param chainId - Chain ID (e.g., 84532 for Base Sepolia)
+     * @returns Canonical DID string (lowercase address)
+     *
+     * @example
+     * ```typescript
+     * const did = DIDResolver.buildDID('0x742d35cc6634c0532925a3b844bc9e7595f0beb', 84532);
+     * // Returns: 'did:ethr:84532:0x742d35cc6634c0532925a3b844bc9e7595f0beb'
+     * ```
+     */
+    static buildDID(address, chainId) {
+        // Validate and checksum address
+        const checksummed = (0, ethers_1.getAddress)(address);
+        // Convert to lowercase for canonical format (per AIP-7 §2.1)
+        const canonical = checksummed.toLowerCase();
+        return `did:ethr:${chainId}:${canonical}`;
+    }
+    /**
+     * Parse DID to extract components
+     *
+     * @param did - DID to parse
+     * @returns Parsed components
+     * @throws ValidationError if DID format is invalid
+     *
+     * @example
+     * ```typescript
+     * const parsed = DIDResolver.parseDID('did:ethr:84532:0x742d35cc6634c0532925a3b844bc9e7595f0beb');
+     * console.log(parsed.method);   // 'ethr'
+     * console.log(parsed.chainId);  // 84532
+     * console.log(parsed.address);  // '0x742d35cc6634c0532925a3b844bc9e7595f0beb'
+     * ```
+     */
+    static parseDID(did) {
+        // Validate basic format
+        if (!did || typeof did !== 'string') {
+            throw new errors_1.ValidationError('did', 'DID must be a non-empty string');
+        }
+        // DID format: did:ethr:<chainId>:<address>
+        const parts = did.split(':');
+        if (parts.length !== 4) {
+            throw new errors_1.ValidationError('did', 'Invalid DID format. Expected: did:ethr:<chainId>:<address>');
+        }
+        const [scheme, method, chainIdStr, address] = parts;
+        // Validate scheme
+        if (scheme !== 'did') {
+            throw new errors_1.ValidationError('did', `Invalid DID scheme: ${scheme}. Expected: did`);
+        }
+        // Validate method
+        if (method !== 'ethr') {
+            throw new errors_1.ValidationError('did', `Invalid DID method: ${method}. Expected: ethr`);
+        }
+        // Validate chainId
+        const chainId = parseInt(chainIdStr, 10);
+        if (isNaN(chainId) || chainId <= 0) {
+            throw new errors_1.ValidationError('did', `Invalid chainId: ${chainIdStr}`);
+        }
+        // Validate address
+        try {
+            const checksummed = (0, ethers_1.getAddress)(address);
+            return {
+                method,
+                chainId,
+                address: checksummed.toLowerCase() // Canonical format per AIP-7
+            };
+        }
+        catch (error) {
+            throw new errors_1.ValidationError('did', `Invalid Ethereum address: ${address}`);
+        }
+    }
+    /**
+     * Validate DID format
+     *
+     * @param did - DID to validate
+     * @returns True if valid, false otherwise
+     */
+    static isValidDID(did) {
+        try {
+            DIDResolver.parseDID(did);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Extract address from DID
+     *
+     * @param did - DID to extract from
+     * @returns Ethereum address (lowercase)
+     * @throws ValidationError if DID format is invalid
+     */
+    static extractAddress(did) {
+        const parsed = DIDResolver.parseDID(did);
+        return parsed.address;
+    }
+    /**
+     * Extract chainId from DID
+     *
+     * @param did - DID to extract from
+     * @returns Chain ID
+     * @throws ValidationError if DID format is invalid
+     */
+    static extractChainId(did) {
+        const parsed = DIDResolver.parseDID(did);
+        return parsed.chainId;
+    }
+    /**
+     * Create domain-separated message to prevent cross-protocol replay attacks
+     *
+     * @param message - Original message
+     * @param chainId - Chain ID for domain separation
+     * @param did - DID for additional context binding
+     * @returns Domain-separated message
+     *
+     * @security
+     * - Binds signature to AGIRAILS protocol
+     * - Binds signature to specific chainId (prevents cross-chain replay)
+     * - Binds signature to specific DID (prevents cross-identity replay)
+     *
+     * @example
+     * ```typescript
+     * const domainMsg = this.createDomainSeparatedMessage('Hello', 84532, 'did:ethr:84532:0x...');
+     * // Returns: "AGIRAILS:84532:did:ethr:84532:0x...\nHello"
+     * ```
+     */
+    createDomainSeparatedMessage(message, chainId, did) {
+        return `AGIRAILS:${chainId}:${did}\n${message}`;
+    }
+    /**
+     * Extract Ethereum address from a verification method
+     *
+     * @param vm - Verification method from DID Document
+     * @returns Ethereum address (checksummed) or null if not found
+     *
+     * @security
+     * - Handles multiple address formats (blockchainAccountId, ethereumAddress, controller DID)
+     * - Validates extracted address format
+     * - Returns null instead of throwing for graceful error handling
+     *
+     * @example
+     * ```typescript
+     * const vm = {
+     *   id: 'did:ethr:84532:0x123...#delegate1',
+     *   type: 'EcdsaSecp256k1RecoveryMethod2020',
+     *   controller: 'did:ethr:84532:0x123...',
+     *   blockchainAccountId: '0x456...@eip155:84532'
+     * };
+     * const address = this.extractAddressFromVerificationMethod(vm);
+     * // Returns: '0x456...' (checksummed)
+     * ```
+     */
+    extractAddressFromVerificationMethod(vm) {
+        // Try blockchainAccountId first (CAIP-10 format: "0x123...@eip155:chainId")
+        if (vm.blockchainAccountId) {
+            const match = vm.blockchainAccountId.match(/^(0x[a-fA-F0-9]{40})@/);
+            if (match) {
+                try {
+                    return (0, ethers_1.getAddress)(match[1]); // Checksum the address
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+        // Try ethereumAddress field
+        if (vm.ethereumAddress) {
+            try {
+                return (0, ethers_1.getAddress)(vm.ethereumAddress);
+            }
+            catch {
+                return null;
+            }
+        }
+        // Try extracting from controller DID
+        if (vm.controller) {
+            try {
+                const { address } = DIDResolver.parseDID(vm.controller);
+                return (0, ethers_1.getAddress)(address); // Already lowercase, checksum it
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+exports.DIDResolver = DIDResolver;
+//# sourceMappingURL=DIDResolver.js.map

package/dist/protocol/DIDResolver.js.map

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

package/dist/protocol/EASHelper.d.ts

@@ -1,5 +1,6 @@
 import { Signer } from 'ethers';
 import { DeliveryProof } from '../types';
+import { IUsedAttestationTracker } from '../utils/UsedAttestationTracker';
 export interface EASConfig {
     contractAddress: string;
     deliveryProofSchemaId: string;
@@ -8,16 +9,70 @@ export interface AttestationResponse {
     uid: string;
     transactionHash: string;
 }
+/**
+ * EASHelper - utility wrapper for Ethereum Attestation Service interactions
+ */
 export declare class EASHelper {
     private readonly config;
     private readonly eas;
-    constructor(signer: Signer, config: EASConfig);
+    private readonly attestationTracker;
+    /**
+     * Create EASHelper instance
+     *
+     * @param signer - Ethers signer for signing attestations
+     * @param config - EAS configuration
+     * @param attestationTracker - Optional tracker for replay attack prevention (C-1 fix)
+     *
+     * SECURITY FIX (NEW-M-2): Validates schema UID format in constructor
+     */
+    constructor(signer: Signer, config: EASConfig, attestationTracker?: IUsedAttestationTracker);
+    /**
+     * Get the attestation tracker for external use
+     */
+    getAttestationTracker(): IUsedAttestationTracker;
+    /**
+     * Create an attestation for a delivery proof. Returns the attestation UID and transaction hash.
+     */
     attestDeliveryProof(proof: DeliveryProof, recipient: string, options?: {
         expirationTime?: number;
         revocable?: boolean;
     }): Promise<AttestationResponse>;
+    /**
+     * Revoke a previously issued attestation by UID.
+     */
     revokeAttestation(uid: string): Promise<string>;
-    getAttestation(uid: string): Promise<any>;
+    /**
+     * Fetch attestation data from the EAS contract.
+     */
+    getAttestation(uid: string): Promise<import("@ethereum-attestation-service/eas-sdk").Attestation>;
+    /**
+     * Verify that a delivery attestation belongs to the specified transaction.
+     *
+     * SECURITY: ACTPKernel V1 accepts any bytes32 as attestationUID without validation.
+     * This means a malicious provider could submit attestation from Transaction A
+     * for Transaction B. This method provides SDK-side protection by verifying:
+     *
+     * 1. Attestation exists and is not revoked
+     * 2. Attestation uses the canonical delivery schema UID
+     * 3. Attestation's txId matches the expected transaction ID
+     * 4. Attestation has not expired
+     *
+     * @param txId - Expected transaction ID (bytes32)
+     * @param attestationUID - Attestation UID to verify (bytes32)
+     * @returns true if attestation is valid for this transaction, false otherwise
+     * @throws Error if attestation is revoked, expired, schema mismatch, or txId mismatch
+     */
     verifyDeliveryAttestation(txId: string, attestationUID: string): Promise<boolean>;
+    /**
+     * Verify attestation for escrow release with mandatory replay protection
+     *
+     * SECURITY FIX (C-4): This method MUST be called before releaseEscrow()
+     * to prevent attestation replay attacks.
+     *
+     * @param txId - Expected transaction ID (bytes32)
+     * @param attestationUID - Attestation UID to verify (bytes32)
+     * @throws Error if verification fails or replay attack detected
+     */
+    verifyAndRecordForRelease(txId: string, attestationUID: string): Promise<void>;
 }
 //# sourceMappingURL=EASHelper.d.ts.map

package/dist/protocol/EASHelper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EASHelper.d.ts","sourceRoot":"","sources":["../../src/protocol/EASHelper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAA0B,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,MAAM,WAAW,SAAS;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;CACzB;AAYD,qBAAa,SAAS;IAGQ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAW;gBAEnB,MAAM,EAAE,MAAM,EAAmB,MAAM,EAAE,SAAS;IAOxD,mBAAmB,CACvB,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GACzD,OAAO,CAAC,mBAAmB,CAAC;IAoDzB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAY/C,cAAc,CAAC,GAAG,EAAE,MAAM;IAqB1B,yBAAyB,CAC7B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,OAAO,CAAC;CAsEpB"}
+{"version":3,"file":"EASHelper.d.ts","sourceRoot":"","sources":["../../src/protocol/EASHelper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EACL,uBAAuB,EAExB,MAAM,iCAAiC,CAAC;AAEzC,MAAM,WAAW,SAAS;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,qBAAa,SAAS;IAelB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAdzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA0B;IAE7D;;;;;;;;OAQG;gBAED,MAAM,EAAE,MAAM,EACG,MAAM,EAAE,SAAS,EAClC,kBAAkB,CAAC,EAAE,uBAAuB;IAsC9C;;OAEG;IACH,qBAAqB,IAAI,uBAAuB;IAIhD;;OAEG;IACG,mBAAmB,CACvB,KAAK,EAAE,aAAa,EACpB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GACzD,OAAO,CAAC,mBAAmB,CAAC;IA4C/B;;OAEG;IACG,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYrD;;OAEG;IACG,cAAc,CAAC,GAAG,EAAE,MAAM;IAOhC;;;;;;;;;;;;;;;;OAgBG;IACG,yBAAyB,CAC7B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,OAAO,CAAC;IAwLnB;;;;;;;;;OASG;IACG,yBAAyB,CAC7B,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC;CAIjB"}