@bsv/wallet-toolbox-client 1.1.0

package/out/src/sdk/CertOps.d.ts

@@ -0,0 +1,66 @@
+import { Base64String, Certificate as BsvCertificate, CertificateFieldNameUnder50Bytes, GetPublicKeyArgs, GetPublicKeyResult, OriginatorDomainNameStringUnder250Bytes, PubKeyHex, WalletCertificate, WalletDecryptArgs, WalletDecryptResult, WalletEncryptArgs, WalletEncryptResult, WalletProtocol } from '@bsv/sdk';
+export interface CertOpsWallet {
+    getPublicKey(args: GetPublicKeyArgs, originator?: OriginatorDomainNameStringUnder250Bytes): Promise<GetPublicKeyResult>;
+    encrypt(args: WalletEncryptArgs, originator?: OriginatorDomainNameStringUnder250Bytes): Promise<WalletEncryptResult>;
+    decrypt(args: WalletDecryptArgs, originator?: OriginatorDomainNameStringUnder250Bytes): Promise<WalletDecryptResult>;
+}
+export declare class CertOps extends BsvCertificate {
+    wallet: CertOpsWallet;
+    _keyring?: Record<CertificateFieldNameUnder50Bytes, string>;
+    _encryptedFields?: Record<CertificateFieldNameUnder50Bytes, Base64String>;
+    _decryptedFields?: Record<CertificateFieldNameUnder50Bytes, string>;
+    constructor(wallet: CertOpsWallet, wc: WalletCertificate);
+    static fromCounterparty(wallet: CertOpsWallet, e: {
+        certificate: WalletCertificate;
+        keyring: Record<CertificateFieldNameUnder50Bytes, string>;
+        counterparty: PubKeyHex;
+    }): Promise<CertOps>;
+    static fromCertifier(wallet: CertOpsWallet, e: {
+        certificate: WalletCertificate;
+        keyring: Record<CertificateFieldNameUnder50Bytes, string>;
+    }): Promise<CertOps>;
+    static fromEncrypted(wallet: CertOpsWallet, wc: WalletCertificate, keyring: Record<CertificateFieldNameUnder50Bytes, string>): Promise<CertOps>;
+    static fromDecrypted(wallet: CertOpsWallet, wc: WalletCertificate): Promise<CertOps>;
+    static copyFields<T>(fields: Record<CertificateFieldNameUnder50Bytes, T>): Record<CertificateFieldNameUnder50Bytes, T>;
+    static getProtocolForCertificateFieldEncryption(serialNumber: string, fieldName: string): {
+        protocolID: WalletProtocol;
+        keyID: string;
+    };
+    exportForSubject(): {
+        certificate: WalletCertificate;
+        keyring: Record<CertificateFieldNameUnder50Bytes, string>;
+    };
+    toWalletCertificate(): WalletCertificate;
+    encryptFields(counterparty?: 'self' | PubKeyHex): Promise<{
+        fields: Record<CertificateFieldNameUnder50Bytes, string>;
+        keyring: Record<CertificateFieldNameUnder50Bytes, string>;
+    }>;
+    decryptFields(counterparty?: PubKeyHex, keyring?: Record<CertificateFieldNameUnder50Bytes, string>): Promise<Record<CertificateFieldNameUnder50Bytes, string>>;
+    exportForCounterparty(
+    /** The incoming counterparty is who they are to us. */
+    counterparty: PubKeyHex, fieldsToReveal: CertificateFieldNameUnder50Bytes[]): Promise<{
+        certificate: WalletCertificate;
+        keyring: Record<CertificateFieldNameUnder50Bytes, string>;
+        counterparty: PubKeyHex;
+    }>;
+    /**
+     * Creates a verifiable certificate structure for a specific verifier, allowing them access to specified fields.
+     * This method decrypts the master field keys for each field specified in `fieldsToReveal` and re-encrypts them
+     * for the verifier's identity key. The resulting certificate structure includes only the fields intended to be
+     * revealed and a verifier-specific keyring for field decryption.
+     *
+     * @param {PubKeyHex} verifierIdentityKey - The public identity key of the verifier who will receive access to the specified fields.
+     * @param {CertificateFieldNameUnder50Bytes[]} fieldsToReveal - An array of field names to be revealed to the verifier. Must be a subset of the certificate's fields.
+     * @returns {Promise<Record<CertificateFieldNameUnder50Bytes[], Base64String>} - A new certificate structure containing the original encrypted fields, the verifier-specific field decryption keyring, and essential certificate metadata.
+     * @throws {WERR_INVALID_PARAMETER} Throws an error if:
+     *   - fieldsToReveal is empty or a field in `fieldsToReveal` does not exist in the certificate.
+     *   - The decrypted master field key fails to decrypt the corresponding field (indicating an invalid key).
+     */
+    createKeyringForVerifier(verifierIdentityKey: PubKeyHex, fieldsToReveal: CertificateFieldNameUnder50Bytes[]): Promise<Record<CertificateFieldNameUnder50Bytes, Base64String>>;
+    /**
+     * encrypt plaintext field values for the subject
+     * update the signature using the certifier's private key.
+     */
+    encryptAndSignNewCertificate(): Promise<void>;
+}
+//# sourceMappingURL=CertOps.d.ts.map

package/out/src/sdk/CertOps.d.ts.map

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

package/out/src/sdk/CertOps.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CertOps = void 0;
+const sdk_1 = require("@bsv/sdk");
+const index_client_1 = require("../index.client");
+const sdk_2 = require("@bsv/sdk");
+const WERR_errors_1 = require("./WERR_errors");
+class CertOps extends sdk_1.Certificate {
+    constructor(wallet, wc) {
+        super(wc.type, wc.serialNumber, wc.subject, wc.certifier, wc.revocationOutpoint, wc.fields, wc.signature);
+        this.wallet = wallet;
+    }
+    static async fromCounterparty(wallet, e) {
+        const c = new CertOps(wallet, e.certificate);
+        // confirm cert verifies and decrypts.
+        await c.verify();
+        await c.decryptFields(e.counterparty, e.keyring);
+        // un-decrypt
+        c.fields = c._encryptedFields;
+        return c;
+    }
+    static async fromCertifier(wallet, e) {
+        return await CertOps.fromCounterparty(wallet, {
+            counterparty: e.certificate.certifier,
+            ...e
+        });
+    }
+    static async fromEncrypted(wallet, wc, keyring) {
+        const c = new CertOps(wallet, wc);
+        c._keyring = keyring;
+        c._encryptedFields = this.copyFields(c.fields);
+        c._decryptedFields = await c.decryptFields();
+        await c.verify();
+        return c;
+    }
+    static async fromDecrypted(wallet, wc) {
+        const c = new CertOps(wallet, wc);
+        ({ fields: c._encryptedFields, keyring: c._keyring } =
+            await c.encryptFields());
+        c._decryptedFields = await c.decryptFields();
+        return c;
+    }
+    static copyFields(fields) {
+        const copy = {};
+        for (const [n, v] of Object.entries(fields))
+            copy[n] = v;
+        return copy;
+    }
+    static getProtocolForCertificateFieldEncryption(serialNumber, fieldName) {
+        return {
+            protocolID: [2, 'certificate field encryption'],
+            keyID: `${serialNumber} ${fieldName}`
+        };
+    }
+    exportForSubject() {
+        if (!this._keyring ||
+            !this._encryptedFields ||
+            !this.signature ||
+            this.signature.length === 0)
+            throw new WERR_errors_1.WERR_INVALID_OPERATION(`Certificate must be encrypted and signed prior to export.`);
+        const certificate = this.toWalletCertificate();
+        const keyring = this._keyring;
+        return { certificate, keyring };
+    }
+    toWalletCertificate() {
+        const wc = {
+            signature: '',
+            ...this
+        };
+        return wc;
+    }
+    async encryptFields(counterparty = 'self') {
+        const fields = this._decryptedFields || this.fields;
+        const encryptedFields = {};
+        const keyring = {};
+        for (const fieldName of Object.keys(fields)) {
+            const fieldSymmetricKey = sdk_2.SymmetricKey.fromRandom();
+            const encryptedFieldValue = fieldSymmetricKey.encrypt(sdk_2.Utils.toArray(this.fields[fieldName], 'utf8'));
+            encryptedFields[fieldName] = sdk_2.Utils.toBase64(encryptedFieldValue);
+            const encryptedFieldKey = await this.wallet.encrypt({
+                plaintext: fieldSymmetricKey.toArray(),
+                counterparty,
+                ...CertOps.getProtocolForCertificateFieldEncryption(this.serialNumber, fieldName)
+            });
+            keyring[fieldName] = sdk_2.Utils.toBase64(encryptedFieldKey.ciphertext);
+        }
+        this._keyring = keyring;
+        this._decryptedFields = fields;
+        this.fields = this._encryptedFields = encryptedFields;
+        return { fields: encryptedFields, keyring };
+    }
+    async decryptFields(counterparty, keyring) {
+        keyring || (keyring = this._keyring);
+        const fields = this._encryptedFields || this.fields;
+        const decryptedFields = {};
+        if (!keyring)
+            throw new index_client_1.sdk.WERR_INVALID_PARAMETER('keyring', 'valid');
+        try {
+            for (const fieldName of Object.keys(keyring)) {
+                const { plaintext: fieldRevelationKey } = await this.wallet.decrypt({
+                    ciphertext: sdk_2.Utils.toArray(keyring[fieldName], 'base64'),
+                    counterparty: counterparty || this.subject,
+                    ...CertOps.getProtocolForCertificateFieldEncryption(this.serialNumber, fieldName)
+                });
+                const fieldValue = new sdk_2.SymmetricKey(fieldRevelationKey).decrypt(sdk_2.Utils.toArray(fields[fieldName], 'base64'));
+                decryptedFields[fieldName] = sdk_2.Utils.toUTF8(fieldValue);
+            }
+            this._keyring = keyring;
+            this._encryptedFields = fields;
+            this.fields = this._decryptedFields = decryptedFields;
+            return decryptedFields;
+        }
+        catch (eu) {
+            const e = index_client_1.sdk.WalletError.fromUnknown(eu);
+            throw e;
+        }
+    }
+    async exportForCounterparty(
+    /** The incoming counterparty is who they are to us. */
+    counterparty, fieldsToReveal) {
+        if (!this._keyring ||
+            !this._encryptedFields ||
+            !this.signature ||
+            this.signature.length === 0)
+            throw new WERR_errors_1.WERR_INVALID_OPERATION(`Certificate must be encrypted and signed prior to export.`);
+        const certificate = this.toWalletCertificate();
+        const keyring = await this.createKeyringForVerifier(counterparty, fieldsToReveal);
+        // The exported counterparty is who we are to them...
+        return {
+            certificate,
+            keyring,
+            counterparty: await (0, index_client_1.getIdentityKey)(this.wallet)
+        };
+    }
+    /**
+     * Creates a verifiable certificate structure for a specific verifier, allowing them access to specified fields.
+     * This method decrypts the master field keys for each field specified in `fieldsToReveal` and re-encrypts them
+     * for the verifier's identity key. The resulting certificate structure includes only the fields intended to be
+     * revealed and a verifier-specific keyring for field decryption.
+     *
+     * @param {PubKeyHex} verifierIdentityKey - The public identity key of the verifier who will receive access to the specified fields.
+     * @param {CertificateFieldNameUnder50Bytes[]} fieldsToReveal - An array of field names to be revealed to the verifier. Must be a subset of the certificate's fields.
+     * @returns {Promise<Record<CertificateFieldNameUnder50Bytes[], Base64String>} - A new certificate structure containing the original encrypted fields, the verifier-specific field decryption keyring, and essential certificate metadata.
+     * @throws {WERR_INVALID_PARAMETER} Throws an error if:
+     *   - fieldsToReveal is empty or a field in `fieldsToReveal` does not exist in the certificate.
+     *   - The decrypted master field key fails to decrypt the corresponding field (indicating an invalid key).
+     */
+    async createKeyringForVerifier(verifierIdentityKey, fieldsToReveal) {
+        if (!this._keyring || !this._encryptedFields)
+            throw new index_client_1.sdk.WERR_INVALID_OPERATION(`certificate must be encrypted`);
+        if (!Array.isArray(fieldsToReveal) ||
+            fieldsToReveal.some(n => this._encryptedFields[n] === undefined))
+            throw new index_client_1.sdk.WERR_INVALID_PARAMETER('fieldsToReveal', `an array of certificate field names`);
+        const fieldRevelationKeyring = {};
+        for (const fieldName of fieldsToReveal) {
+            // Create a keyID
+            const encryptedFieldKey = this._keyring[fieldName];
+            const protocol = CertOps.getProtocolForCertificateFieldEncryption(this.serialNumber, fieldName);
+            // Decrypt the master field key
+            const { plaintext: fieldKey } = await this.wallet.decrypt({
+                ciphertext: sdk_2.Utils.toArray(encryptedFieldKey, 'base64'),
+                counterparty: this.certifier,
+                ...protocol
+            });
+            // Verify that derived key actually decrypts requested field
+            try {
+                new sdk_2.SymmetricKey(fieldKey).decrypt(sdk_2.Utils.toArray(this.fields[fieldName], 'base64'));
+            }
+            catch (_) {
+                throw new index_client_1.sdk.WERR_INTERNAL(`unable to decrypt field "${fieldName}" using derived field key.`);
+            }
+            // Encrypt derived fieldRevelationKey for verifier
+            const { ciphertext: encryptedFieldRevelationKey } = await this.wallet.encrypt({
+                plaintext: fieldKey,
+                counterparty: verifierIdentityKey,
+                ...protocol
+            });
+            // Add encryptedFieldRevelationKey to fieldRevelationKeyring
+            fieldRevelationKeyring[fieldName] = sdk_2.Utils.toBase64(encryptedFieldRevelationKey);
+        }
+        // Return the field revelation keyring which can be used to create a verifiable certificate for a verifier.
+        return fieldRevelationKeyring;
+    }
+    /**
+     * encrypt plaintext field values for the subject
+     * update the signature using the certifier's private key.
+     */
+    async encryptAndSignNewCertificate() {
+        if ((await (0, index_client_1.getIdentityKey)(this.wallet)) !== this.certifier)
+            throw new index_client_1.sdk.WERR_INVALID_PARAMETER('wallet', 'the certifier for new certificate issuance.');
+        await this.encryptFields(this.subject);
+        await this.sign(this.wallet);
+        // Confirm the signed certificate verifies:
+        await this.verify();
+    }
+}
+exports.CertOps = CertOps;
+//# sourceMappingURL=CertOps.js.map

package/out/src/sdk/CertOps.js.map

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

package/out/src/sdk/PrivilegedKeyManager.d.ts

@@ -0,0 +1,125 @@
+import { PrivateKey, CreateHmacArgs, CreateHmacResult, CreateSignatureArgs, CreateSignatureResult, GetPublicKeyArgs, PubKeyHex, RevealCounterpartyKeyLinkageArgs, RevealCounterpartyKeyLinkageResult, RevealSpecificKeyLinkageArgs, RevealSpecificKeyLinkageResult, VerifyHmacArgs, VerifyHmacResult, VerifySignatureArgs, VerifySignatureResult, WalletDecryptArgs, WalletDecryptResult, WalletEncryptArgs, WalletEncryptResult } from '@bsv/sdk';
+/**
+ * PrivilegedKeyManager
+ *
+ * This class manages a privileged (i.e., very sensitive) private key, obtained from
+ * an external function (`keyGetter`), which might be backed by HSMs, secure enclaves,
+ * or other secure storage. The manager retains the key in memory only for a limited
+ * duration (`retentionPeriod`), uses XOR-based chunk-splitting obfuscation, and
+ * includes decoy data to raise the difficulty of discovering the real key in memory.
+ *
+ * IMPORTANT: While these measures raise the bar for attackers, JavaScript environments
+ * do not provide perfect in-memory secrecy.
+ */
+export declare class PrivilegedKeyManager {
+    /**
+     * Function that will retrieve the PrivateKey from a secure environment,
+     * e.g., an HSM or secure enclave. The reason for key usage is passed in
+     * to help with user consent, auditing, and access policy checks.
+     */
+    private keyGetter;
+    /**
+     * Time (in ms) for which the obfuscated key remains in memory
+     * before being automatically destroyed.
+     */
+    private retentionPeriod;
+    /**
+     * A list of dynamically generated property names used to store
+     * real key chunks (XORed with random pads).
+     */
+    private chunkPropNames;
+    /**
+     * A list of dynamically generated property names used to store
+     * the random pads that correspond to the real key chunks.
+     */
+    private chunkPadPropNames;
+    /**
+     * A list of decoy property names that will be removed
+     * when the real key is destroyed.
+     */
+    private decoyPropNamesDestroy;
+    /**
+     * A list of decoy property names that remain in memory
+     * even after the real key is destroyed (just to cause confusion).
+     */
+    private decoyPropNamesRemain;
+    /**
+     * Handle to the timer that will remove the key from memory
+     * after the retention period. If the key is refreshed again
+     * within that period, the timer is cleared and re-set.
+     */
+    private destroyTimer;
+    /**
+     * Number of chunks to split the 32-byte key into.
+     * Adjust to increase or decrease obfuscation complexity.
+     */
+    private readonly CHUNK_COUNT;
+    /**
+     * @param keyGetter - Asynchronous function that retrieves the PrivateKey from a secure environment.
+     * @param retentionPeriod - Time in milliseconds to retain the obfuscated key in memory before zeroizing.
+     */
+    constructor(keyGetter: (reason: string) => Promise<PrivateKey>, retentionPeriod?: number);
+    /**
+     * Safely destroys the in-memory obfuscated key material by zeroizing
+     * and deleting related fields. Also destroys some (but not all) decoy
+     * properties to further confuse an attacker.
+     */
+    destroyKey(): void;
+    /**
+     * Re/sets the destruction timer that removes the key from memory
+     * after `retentionPeriod` ms. If a timer is already running, it
+     * is cleared and re-set. This ensures the key remains in memory
+     * for exactly the desired window after its most recent acquisition.
+     */
+    private scheduleKeyDestruction;
+    /**
+     * XOR-based obfuscation on a per-chunk basis.
+     * This function takes two equal-length byte arrays
+     * and returns the XOR combination.
+     */
+    private xorBytes;
+    /**
+     * Splits the 32-byte key into `this.CHUNK_COUNT` smaller chunks
+     * (mostly equal length; the last chunk picks up leftover bytes
+     * if 32 is not evenly divisible).
+     */
+    private splitKeyIntoChunks;
+    /**
+     * Reassembles the chunks from the dynamic properties, XORs them
+     * with their corresponding pads, and returns a single 32-byte
+     * Uint8Array representing the raw key.
+     */
+    private reassembleKeyFromChunks;
+    /**
+     * Generates a random property name to store key chunks or decoy data.
+     */
+    private generateRandomPropName;
+    /**
+     * Forces a PrivateKey to be represented as exactly 32 bytes, left-padding
+     * with zeros if its numeric value has fewer than 32 bytes.
+     */
+    private get32ByteRepresentation;
+    /**
+     * Returns the privileged key needed to perform cryptographic operations.
+     * Uses in-memory chunk-based obfuscation if the key was already fetched.
+     * Otherwise, it calls out to `keyGetter`, splits the 32-byte representation
+     * of the key, XORs each chunk with a random pad, and stores them under
+     * dynamic property names. Also populates new decoy properties.
+     *
+     * @param reason - The reason for why the key is needed, passed to keyGetter.
+     * @returns The PrivateKey object needed for cryptographic operations.
+     */
+    private getPrivilegedKey;
+    getPublicKey(args: GetPublicKeyArgs): Promise<{
+        publicKey: PubKeyHex;
+    }>;
+    revealCounterpartyKeyLinkage(args: RevealCounterpartyKeyLinkageArgs): Promise<RevealCounterpartyKeyLinkageResult>;
+    revealSpecificKeyLinkage(args: RevealSpecificKeyLinkageArgs): Promise<RevealSpecificKeyLinkageResult>;
+    encrypt(args: WalletEncryptArgs): Promise<WalletEncryptResult>;
+    decrypt(args: WalletDecryptArgs): Promise<WalletDecryptResult>;
+    createHmac(args: CreateHmacArgs): Promise<CreateHmacResult>;
+    verifyHmac(args: VerifyHmacArgs): Promise<VerifyHmacResult>;
+    createSignature(args: CreateSignatureArgs): Promise<CreateSignatureResult>;
+    verifySignature(args: VerifySignatureArgs): Promise<VerifySignatureResult>;
+}
+//# sourceMappingURL=PrivilegedKeyManager.d.ts.map

package/out/src/sdk/PrivilegedKeyManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrivilegedKeyManager.d.ts","sourceRoot":"","sources":["../../../../src/sdk/PrivilegedKeyManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAEhB,SAAS,EACT,gCAAgC,EAChC,kCAAkC,EAClC,4BAA4B,EAC5B,8BAA8B,EAC9B,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,UAAU,CAAA;AAEjB;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAoB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,SAAS,CAAyC;IAE1D;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAQ;IAE/B;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAe;IAErC;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAAe;IAExC;;;OAGG;IACH,OAAO,CAAC,qBAAqB,CAAe;IAE5C;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAAe;IAE3C;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAiB;IAErC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAI;IAEhC;;;OAGG;gBAED,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,EAClD,eAAe,SAAU;IAc3B;;;;OAIG;IACH,UAAU,IAAI,IAAI;IAyClB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAU9B;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAQhB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAiC/B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAM9B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAe/B;;;;;;;;;OASG;YACW,gBAAgB;IA4DxB,YAAY,CAChB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC;QAAE,SAAS,EAAE,SAAS,CAAA;KAAE,CAAC;IAM9B,4BAA4B,CAChC,IAAI,EAAE,gCAAgC,GACrC,OAAO,CAAC,kCAAkC,CAAC;IAMxC,wBAAwB,CAC5B,IAAI,EAAE,4BAA4B,GACjC,OAAO,CAAC,8BAA8B,CAAC;IAMpC,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAM9D,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAM9D,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM3D,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAM3D,eAAe,CACnB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC;IAM3B,eAAe,CACnB,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC;CAKlC"}