@metamask-previews/chain-agnostic-permission 0.1.0-preview-b69c669

package/dist/caip25Permission.cjs

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Caip25CaveatMutators = exports.caip25EndowmentBuilder = exports.caip25CaveatBuilder = exports.diffScopesForCaip25CaveatValue = exports.createCaip25Caveat = exports.Caip25EndowmentPermissionName = exports.Caip25CaveatType = void 0;
+const permission_controller_1 = require("@metamask/permission-controller");
+const utils_1 = require("@metamask/utils");
+const lodash_1 = require("lodash");
+const assert_1 = require("./scope/assert.cjs");
+const supported_1 = require("./scope/supported.cjs");
+const transform_1 = require("./scope/transform.cjs");
+const types_1 = require("./scope/types.cjs");
+/**
+ * The name of the CAIP-25 permission caveat.
+ */
+exports.Caip25CaveatType = 'authorizedScopes';
+/**
+ * The target name of the CAIP-25 endowment permission.
+ */
+exports.Caip25EndowmentPermissionName = 'endowment:caip25';
+/**
+ * Creates a CAIP-25 permission caveat.
+ *
+ * @param value - The CAIP-25 permission caveat value.
+ * @returns The CAIP-25 permission caveat (now including the type).
+ */
+const createCaip25Caveat = (value) => {
+    return {
+        type: exports.Caip25CaveatType,
+        value,
+    };
+};
+exports.createCaip25Caveat = createCaip25Caveat;
+/**
+ * Calculates the difference between two provided CAIP-25 permission caveat values, but only considering a single scope property at a time.
+ *
+ * @param originalValue - The existing CAIP-25 permission caveat value.
+ * @param mergedValue - The result from merging existing and incoming CAIP-25 permission caveat values.
+ * @param scopeToDiff - The required or optional scopes from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request.
+ * @returns The difference between original and merged CAIP-25 permission caveat values.
+ */
+function diffScopesForCaip25CaveatValue(originalValue, mergedValue, scopeToDiff) {
+    const diff = (0, lodash_1.cloneDeep)(originalValue);
+    const mergedScopeToDiff = mergedValue[scopeToDiff];
+    for (const [scopeString, mergedScopeObject] of Object.entries(mergedScopeToDiff)) {
+        const internalScopeString = scopeString;
+        const originalScopeObject = diff[scopeToDiff][internalScopeString];
+        if (originalScopeObject) {
+            const newAccounts = mergedScopeObject.accounts.filter((account) => !originalScopeObject?.accounts.includes(account));
+            if (newAccounts.length > 0) {
+                diff[scopeToDiff][internalScopeString] = {
+                    accounts: newAccounts,
+                };
+                continue;
+            }
+            delete diff[scopeToDiff][internalScopeString];
+        }
+        else {
+            diff[scopeToDiff][internalScopeString] = mergedScopeObject;
+        }
+    }
+    return diff;
+}
+exports.diffScopesForCaip25CaveatValue = diffScopesForCaip25CaveatValue;
+/**
+ * Checks if every account in the given scopes object is supported.
+ *
+ * @param scopesObject - The scopes object to iterate over.
+ * @param listAccounts - The hook for getting internalAccount objects for all evm accounts.
+ * @param getNonEvmAccountAddresses - The hook that returns the supported CAIP-10 account addresses for a non EVM scope.
+ * addresses.
+ * @returns True if every account in the scopes object is supported, false otherwise.
+ */
+function isEveryAccountInScopesObjectSupported(scopesObject, listAccounts, getNonEvmAccountAddresses) {
+    return Object.values(scopesObject).every((scopeObject) => scopeObject.accounts.every((account) => (0, supported_1.isSupportedAccount)(account, {
+        getEvmInternalAccounts: listAccounts,
+        getNonEvmAccountAddresses,
+    })));
+}
+/**
+ * Helper that returns a `authorizedScopes` CAIP-25 caveat specification
+ * that can be passed into the PermissionController constructor.
+ *
+ * @param options - The specification builder options.
+ * @param options.findNetworkClientIdByChainId - The hook for getting the networkClientId that serves a chainId.
+ * @param options.listAccounts - The hook for getting internalAccount objects for all evm accounts.
+ * @param options.isNonEvmScopeSupported - The hook that determines if an non EVM scopeString is supported.
+ * @param options.getNonEvmAccountAddresses - The hook that returns the supported CAIP-10 account addresses for a non EVM scope.
+ * @returns The specification for the `caip25` caveat.
+ */
+const caip25CaveatBuilder = ({ findNetworkClientIdByChainId, listAccounts, isNonEvmScopeSupported, getNonEvmAccountAddresses, }) => {
+    return {
+        type: exports.Caip25CaveatType,
+        validator: (caveat, _origin, _target) => {
+            if (!caveat.value ||
+                !(0, utils_1.hasProperty)(caveat.value, 'requiredScopes') ||
+                !(0, utils_1.hasProperty)(caveat.value, 'optionalScopes') ||
+                !(0, utils_1.hasProperty)(caveat.value, 'isMultichainOrigin') ||
+                typeof caveat.value.isMultichainOrigin !== 'boolean') {
+                throw new Error(`${exports.Caip25EndowmentPermissionName} error: Received invalid value for caveat of type "${exports.Caip25CaveatType}".`);
+            }
+            const { requiredScopes, optionalScopes } = caveat.value;
+            (0, assert_1.assertIsInternalScopesObject)(requiredScopes);
+            (0, assert_1.assertIsInternalScopesObject)(optionalScopes);
+            const isEvmChainIdSupported = (chainId) => {
+                try {
+                    findNetworkClientIdByChainId(chainId);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const allRequiredScopesSupported = Object.keys(requiredScopes).every((scopeString) => (0, supported_1.isSupportedScopeString)(scopeString, {
+                isEvmChainIdSupported,
+                isNonEvmScopeSupported,
+            }));
+            const allOptionalScopesSupported = Object.keys(optionalScopes).every((scopeString) => (0, supported_1.isSupportedScopeString)(scopeString, {
+                isEvmChainIdSupported,
+                isNonEvmScopeSupported,
+            }));
+            if (!allRequiredScopesSupported || !allOptionalScopesSupported) {
+                throw new Error(`${exports.Caip25EndowmentPermissionName} error: Received scopeString value(s) for caveat of type "${exports.Caip25CaveatType}" that are not supported by the wallet.`);
+            }
+            const allRequiredAccountsSupported = isEveryAccountInScopesObjectSupported(requiredScopes, listAccounts, getNonEvmAccountAddresses);
+            const allOptionalAccountsSupported = isEveryAccountInScopesObjectSupported(optionalScopes, listAccounts, getNonEvmAccountAddresses);
+            if (!allRequiredAccountsSupported || !allOptionalAccountsSupported) {
+                throw new Error(`${exports.Caip25EndowmentPermissionName} error: Received account value(s) for caveat of type "${exports.Caip25CaveatType}" that are not supported by the wallet.`);
+            }
+        },
+        merger: (leftValue, rightValue) => {
+            const mergedRequiredScopes = (0, transform_1.mergeInternalScopes)(leftValue.requiredScopes, rightValue.requiredScopes);
+            const mergedOptionalScopes = (0, transform_1.mergeInternalScopes)(leftValue.optionalScopes, rightValue.optionalScopes);
+            const mergedValue = {
+                requiredScopes: mergedRequiredScopes,
+                optionalScopes: mergedOptionalScopes,
+                isMultichainOrigin: leftValue.isMultichainOrigin,
+            };
+            const partialDiff = diffScopesForCaip25CaveatValue(leftValue, mergedValue, 'requiredScopes');
+            const diff = diffScopesForCaip25CaveatValue(partialDiff, mergedValue, 'optionalScopes');
+            return [mergedValue, diff];
+        },
+    };
+};
+exports.caip25CaveatBuilder = caip25CaveatBuilder;
+/**
+ * Helper that returns a `endowment:caip25` specification that
+ * can be passed into the PermissionController constructor.
+ *
+ * @returns The specification for the `caip25` endowment.
+ */
+const specificationBuilder = () => {
+    return {
+        permissionType: permission_controller_1.PermissionType.Endowment,
+        targetName: exports.Caip25EndowmentPermissionName,
+        allowedCaveats: [exports.Caip25CaveatType],
+        endowmentGetter: (_getterOptions) => null,
+        validator: (permission) => {
+            if (permission.caveats?.length !== 1 ||
+                permission.caveats?.[0]?.type !== exports.Caip25CaveatType) {
+                throw new Error(`${exports.Caip25EndowmentPermissionName} error: Invalid caveats. There must be a single caveat of type "${exports.Caip25CaveatType}".`);
+            }
+        },
+    };
+};
+/**
+ * The `caip25` endowment specification builder. Passed to the
+ * `PermissionController` for constructing and validating the
+ * `endowment:caip25` permission.
+ */
+exports.caip25EndowmentBuilder = Object.freeze({
+    targetName: exports.Caip25EndowmentPermissionName,
+    specificationBuilder,
+});
+/**
+ * Factories that construct caveat mutator functions that are passed to
+ * PermissionController.updatePermissionsByCaveat.
+ */
+exports.Caip25CaveatMutators = {
+    [exports.Caip25CaveatType]: {
+        removeScope,
+        removeAccount,
+    },
+};
+/**
+ * Removes the account from the scope object.
+ *
+ * @param targetAddress - The address to remove from the scope object.
+ * @returns A function that removes the account from the scope object.
+ */
+function removeAccountFilterFn(targetAddress) {
+    return (account) => {
+        const parsed = (0, utils_1.parseCaipAccountId)(account);
+        return parsed.address !== targetAddress;
+    };
+}
+/**
+ * Removes the account from the scope object.
+ *
+ * @param scopeObject - The scope object to remove the account from.
+ * @param targetAddress - The address to remove from the scope object.
+ */
+function removeAccountFromScopeObject(scopeObject, targetAddress) {
+    if (scopeObject.accounts) {
+        scopeObject.accounts = scopeObject.accounts.filter(removeAccountFilterFn(targetAddress));
+    }
+}
+/**
+ * Removes the target account from the scope object.
+ *
+ * @param caip25CaveatValue - The CAIP-25 permission caveat value from which to remove the account (across all chain scopes).
+ * @param targetAddress - The address to remove from the scope object. Not a CAIP-10 formatted address because it will be removed across each chain scope.
+ * @returns The updated scope object.
+ */
+function removeAccount(caip25CaveatValue, targetAddress) {
+    const updatedCaveatValue = (0, lodash_1.cloneDeep)(caip25CaveatValue);
+    [
+        updatedCaveatValue.requiredScopes,
+        updatedCaveatValue.optionalScopes,
+    ].forEach((scopes) => {
+        Object.entries(scopes).forEach(([, scopeObject]) => {
+            removeAccountFromScopeObject(scopeObject, targetAddress);
+        });
+    });
+    const noChange = (0, lodash_1.isEqual)(updatedCaveatValue, caip25CaveatValue);
+    if (noChange) {
+        return {
+            operation: permission_controller_1.CaveatMutatorOperation.Noop,
+        };
+    }
+    const hasAccounts = [
+        ...Object.values(updatedCaveatValue.requiredScopes),
+        ...Object.values(updatedCaveatValue.optionalScopes),
+    ].some(({ accounts }) => accounts.length > 0);
+    if (hasAccounts) {
+        return {
+            operation: permission_controller_1.CaveatMutatorOperation.UpdateValue,
+            value: updatedCaveatValue,
+        };
+    }
+    return {
+        operation: permission_controller_1.CaveatMutatorOperation.RevokePermission,
+    };
+}
+/**
+ * Removes the target scope from the value arrays of the given
+ * `endowment:caip25` caveat. No-ops if the target scopeString is not in
+ * the existing scopes.
+ *
+ * @param caip25CaveatValue - The CAIP-25 permission caveat value to remove the scope from.
+ * @param targetScopeString - The scope that is being removed.
+ * @returns The updated CAIP-25 permission caveat value.
+ */
+function removeScope(caip25CaveatValue, targetScopeString) {
+    const newRequiredScopes = Object.entries(caip25CaveatValue.requiredScopes).filter(([scope]) => scope !== targetScopeString);
+    const newOptionalScopes = Object.entries(caip25CaveatValue.optionalScopes).filter(([scope]) => {
+        return scope !== targetScopeString;
+    });
+    const requiredScopesRemoved = newRequiredScopes.length !==
+        Object.keys(caip25CaveatValue.requiredScopes).length;
+    const optionalScopesRemoved = newOptionalScopes.length !==
+        Object.keys(caip25CaveatValue.optionalScopes).length;
+    if (!requiredScopesRemoved && !optionalScopesRemoved) {
+        return {
+            operation: permission_controller_1.CaveatMutatorOperation.Noop,
+        };
+    }
+    const updatedCaveatValue = {
+        ...caip25CaveatValue,
+        requiredScopes: Object.fromEntries(newRequiredScopes),
+        optionalScopes: Object.fromEntries(newOptionalScopes),
+    };
+    const hasNonWalletScopes = [...newRequiredScopes, ...newOptionalScopes].some(([scopeString]) => {
+        const { namespace } = (0, types_1.parseScopeString)(scopeString);
+        return namespace !== utils_1.KnownCaipNamespace.Wallet;
+    });
+    if (hasNonWalletScopes) {
+        return {
+            operation: permission_controller_1.CaveatMutatorOperation.UpdateValue,
+            value: updatedCaveatValue,
+        };
+    }
+    return {
+        operation: permission_controller_1.CaveatMutatorOperation.RevokePermission,
+    };
+}
+//# sourceMappingURL=caip25Permission.cjs.map

package/dist/caip25Permission.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"caip25Permission.cjs","sourceRoot":"","sources":["../src/caip25Permission.ts"],"names":[],"mappings":"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","sourcesContent":["import type { NetworkClientId } from '@metamask/network-controller';\nimport type {\n  PermissionSpecificationBuilder,\n  EndowmentGetterParams,\n  ValidPermissionSpecification,\n  PermissionValidatorConstraint,\n  PermissionConstraint,\n  EndowmentCaveatSpecificationConstraint,\n} from '@metamask/permission-controller';\nimport {\n  CaveatMutatorOperation,\n  PermissionType,\n} from '@metamask/permission-controller';\nimport type { CaipAccountId, CaipChainId, Json } from '@metamask/utils';\nimport {\n  hasProperty,\n  KnownCaipNamespace,\n  parseCaipAccountId,\n  type Hex,\n  type NonEmptyArray,\n} from '@metamask/utils';\nimport { cloneDeep, isEqual } from 'lodash';\n\nimport { assertIsInternalScopesObject } from './scope/assert';\nimport { isSupportedAccount, isSupportedScopeString } from './scope/supported';\nimport { mergeInternalScopes } from './scope/transform';\nimport {\n  parseScopeString,\n  type ExternalScopeString,\n  type InternalScopeObject,\n  type InternalScopesObject,\n} from './scope/types';\n\n/**\n * The CAIP-25 permission caveat value.\n * This permission contains the required and optional scopes and session properties from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request that initiated the permission session.\n * It also contains a boolean (isMultichainOrigin) indicating if the permission session is multichain, which may be needed to determine implicit permissioning.\n */\nexport type Caip25CaveatValue = {\n  requiredScopes: InternalScopesObject;\n  optionalScopes: InternalScopesObject;\n  sessionProperties?: Record<string, Json>;\n  isMultichainOrigin: boolean;\n};\n\n/**\n * The name of the CAIP-25 permission caveat.\n */\nexport const Caip25CaveatType = 'authorizedScopes';\n\n/**\n * The target name of the CAIP-25 endowment permission.\n */\nexport const Caip25EndowmentPermissionName = 'endowment:caip25';\n\n/**\n * Creates a CAIP-25 permission caveat.\n *\n * @param value - The CAIP-25 permission caveat value.\n * @returns The CAIP-25 permission caveat (now including the type).\n */\nexport const createCaip25Caveat = (value: Caip25CaveatValue) => {\n  return {\n    type: Caip25CaveatType,\n    value,\n  };\n};\n\ntype Caip25EndowmentCaveatSpecificationBuilderOptions = {\n  findNetworkClientIdByChainId: (chainId: Hex) => NetworkClientId;\n  listAccounts: () => { type: string; address: Hex }[];\n  isNonEvmScopeSupported: (scope: CaipChainId) => boolean;\n  getNonEvmAccountAddresses: (scope: CaipChainId) => string[];\n};\n\n/**\n * Calculates the difference between two provided CAIP-25 permission caveat values, but only considering a single scope property at a time.\n *\n * @param originalValue - The existing CAIP-25 permission caveat value.\n * @param mergedValue - The result from merging existing and incoming CAIP-25 permission caveat values.\n * @param scopeToDiff - The required or optional scopes from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request.\n * @returns The difference between original and merged CAIP-25 permission caveat values.\n */\nexport function diffScopesForCaip25CaveatValue(\n  originalValue: Caip25CaveatValue,\n  mergedValue: Caip25CaveatValue,\n  scopeToDiff: 'optionalScopes' | 'requiredScopes',\n): Caip25CaveatValue {\n  const diff = cloneDeep(originalValue);\n\n  const mergedScopeToDiff = mergedValue[scopeToDiff];\n  for (const [scopeString, mergedScopeObject] of Object.entries(\n    mergedScopeToDiff,\n  )) {\n    const internalScopeString = scopeString as keyof typeof mergedScopeToDiff;\n    const originalScopeObject = diff[scopeToDiff][internalScopeString];\n\n    if (originalScopeObject) {\n      const newAccounts = mergedScopeObject.accounts.filter(\n        (account) => !originalScopeObject?.accounts.includes(account),\n      );\n      if (newAccounts.length > 0) {\n        diff[scopeToDiff][internalScopeString] = {\n          accounts: newAccounts,\n        };\n        continue;\n      }\n      delete diff[scopeToDiff][internalScopeString];\n    } else {\n      diff[scopeToDiff][internalScopeString] = mergedScopeObject;\n    }\n  }\n\n  return diff;\n}\n\n/**\n * Checks if every account in the given scopes object is supported.\n *\n * @param scopesObject - The scopes object to iterate over.\n * @param listAccounts - The hook for getting internalAccount objects for all evm accounts.\n * @param getNonEvmAccountAddresses - The hook that returns the supported CAIP-10 account addresses for a non EVM scope.\n * addresses.\n * @returns True if every account in the scopes object is supported, false otherwise.\n */\nfunction isEveryAccountInScopesObjectSupported(\n  scopesObject: InternalScopesObject,\n  listAccounts: () => { type: string; address: Hex }[],\n  getNonEvmAccountAddresses: (scope: CaipChainId) => string[],\n) {\n  return Object.values(scopesObject).every((scopeObject) =>\n    scopeObject.accounts.every((account) =>\n      isSupportedAccount(account, {\n        getEvmInternalAccounts: listAccounts,\n        getNonEvmAccountAddresses,\n      }),\n    ),\n  );\n}\n\n/**\n * Helper that returns a `authorizedScopes` CAIP-25 caveat specification\n * that can be passed into the PermissionController constructor.\n *\n * @param options - The specification builder options.\n * @param options.findNetworkClientIdByChainId - The hook for getting the networkClientId that serves a chainId.\n * @param options.listAccounts - The hook for getting internalAccount objects for all evm accounts.\n * @param options.isNonEvmScopeSupported - The hook that determines if an non EVM scopeString is supported.\n * @param options.getNonEvmAccountAddresses - The hook that returns the supported CAIP-10 account addresses for a non EVM scope.\n * @returns The specification for the `caip25` caveat.\n */\nexport const caip25CaveatBuilder = ({\n  findNetworkClientIdByChainId,\n  listAccounts,\n  isNonEvmScopeSupported,\n  getNonEvmAccountAddresses,\n}: Caip25EndowmentCaveatSpecificationBuilderOptions): EndowmentCaveatSpecificationConstraint &\n  Required<\n    Pick<EndowmentCaveatSpecificationConstraint, 'validator' | 'merger'>\n  > => {\n  return {\n    type: Caip25CaveatType,\n    validator: (\n      caveat: { type: typeof Caip25CaveatType; value: unknown },\n      _origin?: string,\n      _target?: string,\n    ) => {\n      if (\n        !caveat.value ||\n        !hasProperty(caveat.value, 'requiredScopes') ||\n        !hasProperty(caveat.value, 'optionalScopes') ||\n        !hasProperty(caveat.value, 'isMultichainOrigin') ||\n        typeof caveat.value.isMultichainOrigin !== 'boolean'\n      ) {\n        throw new Error(\n          `${Caip25EndowmentPermissionName} error: Received invalid value for caveat of type \"${Caip25CaveatType}\".`,\n        );\n      }\n\n      const { requiredScopes, optionalScopes } = caveat.value;\n\n      assertIsInternalScopesObject(requiredScopes);\n      assertIsInternalScopesObject(optionalScopes);\n\n      const isEvmChainIdSupported = (chainId: Hex) => {\n        try {\n          findNetworkClientIdByChainId(chainId);\n          return true;\n        } catch {\n          return false;\n        }\n      };\n\n      const allRequiredScopesSupported = Object.keys(requiredScopes).every(\n        (scopeString) =>\n          isSupportedScopeString(scopeString, {\n            isEvmChainIdSupported,\n            isNonEvmScopeSupported,\n          }),\n      );\n      const allOptionalScopesSupported = Object.keys(optionalScopes).every(\n        (scopeString) =>\n          isSupportedScopeString(scopeString, {\n            isEvmChainIdSupported,\n            isNonEvmScopeSupported,\n          }),\n      );\n      if (!allRequiredScopesSupported || !allOptionalScopesSupported) {\n        throw new Error(\n          `${Caip25EndowmentPermissionName} error: Received scopeString value(s) for caveat of type \"${Caip25CaveatType}\" that are not supported by the wallet.`,\n        );\n      }\n\n      const allRequiredAccountsSupported =\n        isEveryAccountInScopesObjectSupported(\n          requiredScopes,\n          listAccounts,\n          getNonEvmAccountAddresses,\n        );\n      const allOptionalAccountsSupported =\n        isEveryAccountInScopesObjectSupported(\n          optionalScopes,\n          listAccounts,\n          getNonEvmAccountAddresses,\n        );\n      if (!allRequiredAccountsSupported || !allOptionalAccountsSupported) {\n        throw new Error(\n          `${Caip25EndowmentPermissionName} error: Received account value(s) for caveat of type \"${Caip25CaveatType}\" that are not supported by the wallet.`,\n        );\n      }\n    },\n    merger: (\n      leftValue: Caip25CaveatValue,\n      rightValue: Caip25CaveatValue,\n    ): [Caip25CaveatValue, Caip25CaveatValue] => {\n      const mergedRequiredScopes = mergeInternalScopes(\n        leftValue.requiredScopes,\n        rightValue.requiredScopes,\n      );\n      const mergedOptionalScopes = mergeInternalScopes(\n        leftValue.optionalScopes,\n        rightValue.optionalScopes,\n      );\n\n      const mergedValue: Caip25CaveatValue = {\n        requiredScopes: mergedRequiredScopes,\n        optionalScopes: mergedOptionalScopes,\n        isMultichainOrigin: leftValue.isMultichainOrigin,\n      };\n\n      const partialDiff = diffScopesForCaip25CaveatValue(\n        leftValue,\n        mergedValue,\n        'requiredScopes',\n      );\n\n      const diff = diffScopesForCaip25CaveatValue(\n        partialDiff,\n        mergedValue,\n        'optionalScopes',\n      );\n\n      return [mergedValue, diff];\n    },\n  };\n};\n\ntype Caip25EndowmentSpecification = ValidPermissionSpecification<{\n  permissionType: PermissionType.Endowment;\n  targetName: typeof Caip25EndowmentPermissionName;\n  endowmentGetter: (_options?: EndowmentGetterParams) => null;\n  validator: PermissionValidatorConstraint;\n  allowedCaveats: Readonly<NonEmptyArray<string>> | null;\n}>;\n\n/**\n * Helper that returns a `endowment:caip25` specification that\n * can be passed into the PermissionController constructor.\n *\n * @returns The specification for the `caip25` endowment.\n */\nconst specificationBuilder: PermissionSpecificationBuilder<\n  PermissionType.Endowment,\n  Record<never, never>,\n  Caip25EndowmentSpecification\n> = () => {\n  return {\n    permissionType: PermissionType.Endowment,\n    targetName: Caip25EndowmentPermissionName,\n    allowedCaveats: [Caip25CaveatType],\n    endowmentGetter: (_getterOptions?: EndowmentGetterParams) => null,\n    validator: (permission: PermissionConstraint) => {\n      if (\n        permission.caveats?.length !== 1 ||\n        permission.caveats?.[0]?.type !== Caip25CaveatType\n      ) {\n        throw new Error(\n          `${Caip25EndowmentPermissionName} error: Invalid caveats. There must be a single caveat of type \"${Caip25CaveatType}\".`,\n        );\n      }\n    },\n  };\n};\n\n/**\n * The `caip25` endowment specification builder. Passed to the\n * `PermissionController` for constructing and validating the\n * `endowment:caip25` permission.\n */\nexport const caip25EndowmentBuilder = Object.freeze({\n  targetName: Caip25EndowmentPermissionName,\n  specificationBuilder,\n} as const);\n\n/**\n * Factories that construct caveat mutator functions that are passed to\n * PermissionController.updatePermissionsByCaveat.\n */\nexport const Caip25CaveatMutators = {\n  [Caip25CaveatType]: {\n    removeScope,\n    removeAccount,\n  },\n};\n\n/**\n * Removes the account from the scope object.\n *\n * @param targetAddress - The address to remove from the scope object.\n * @returns A function that removes the account from the scope object.\n */\nfunction removeAccountFilterFn(targetAddress: string) {\n  return (account: CaipAccountId) => {\n    const parsed = parseCaipAccountId(account);\n    return parsed.address !== targetAddress;\n  };\n}\n\n/**\n * Removes the account from the scope object.\n *\n * @param scopeObject - The scope object to remove the account from.\n * @param targetAddress - The address to remove from the scope object.\n */\nfunction removeAccountFromScopeObject(\n  scopeObject: InternalScopeObject,\n  targetAddress: string,\n) {\n  if (scopeObject.accounts) {\n    scopeObject.accounts = scopeObject.accounts.filter(\n      removeAccountFilterFn(targetAddress),\n    );\n  }\n}\n\n/**\n * Removes the target account from the scope object.\n *\n * @param caip25CaveatValue - The CAIP-25 permission caveat value from which to remove the account (across all chain scopes).\n * @param targetAddress - The address to remove from the scope object. Not a CAIP-10 formatted address because it will be removed across each chain scope.\n * @returns The updated scope object.\n */\nfunction removeAccount(\n  caip25CaveatValue: Caip25CaveatValue,\n  targetAddress: Hex,\n) {\n  const updatedCaveatValue = cloneDeep(caip25CaveatValue);\n\n  [\n    updatedCaveatValue.requiredScopes,\n    updatedCaveatValue.optionalScopes,\n  ].forEach((scopes) => {\n    Object.entries(scopes).forEach(([, scopeObject]) => {\n      removeAccountFromScopeObject(scopeObject, targetAddress);\n    });\n  });\n\n  const noChange = isEqual(updatedCaveatValue, caip25CaveatValue);\n\n  if (noChange) {\n    return {\n      operation: CaveatMutatorOperation.Noop,\n    };\n  }\n\n  const hasAccounts = [\n    ...Object.values(updatedCaveatValue.requiredScopes),\n    ...Object.values(updatedCaveatValue.optionalScopes),\n  ].some(({ accounts }) => accounts.length > 0);\n\n  if (hasAccounts) {\n    return {\n      operation: CaveatMutatorOperation.UpdateValue,\n      value: updatedCaveatValue,\n    };\n  }\n\n  return {\n    operation: CaveatMutatorOperation.RevokePermission,\n  };\n}\n\n/**\n * Removes the target scope from the value arrays of the given\n * `endowment:caip25` caveat. No-ops if the target scopeString is not in\n * the existing scopes.\n *\n * @param caip25CaveatValue - The CAIP-25 permission caveat value to remove the scope from.\n * @param targetScopeString - The scope that is being removed.\n * @returns The updated CAIP-25 permission caveat value.\n */\nfunction removeScope(\n  caip25CaveatValue: Caip25CaveatValue,\n  targetScopeString: ExternalScopeString,\n) {\n  const newRequiredScopes = Object.entries(\n    caip25CaveatValue.requiredScopes,\n  ).filter(([scope]) => scope !== targetScopeString);\n  const newOptionalScopes = Object.entries(\n    caip25CaveatValue.optionalScopes,\n  ).filter(([scope]) => {\n    return scope !== targetScopeString;\n  });\n\n  const requiredScopesRemoved =\n    newRequiredScopes.length !==\n    Object.keys(caip25CaveatValue.requiredScopes).length;\n  const optionalScopesRemoved =\n    newOptionalScopes.length !==\n    Object.keys(caip25CaveatValue.optionalScopes).length;\n\n  if (!requiredScopesRemoved && !optionalScopesRemoved) {\n    return {\n      operation: CaveatMutatorOperation.Noop,\n    };\n  }\n\n  const updatedCaveatValue = {\n    ...caip25CaveatValue,\n    requiredScopes: Object.fromEntries(newRequiredScopes),\n    optionalScopes: Object.fromEntries(newOptionalScopes),\n  };\n\n  const hasNonWalletScopes = [...newRequiredScopes, ...newOptionalScopes].some(\n    ([scopeString]) => {\n      const { namespace } = parseScopeString(scopeString);\n      return namespace !== KnownCaipNamespace.Wallet;\n    },\n  );\n\n  if (hasNonWalletScopes) {\n    return {\n      operation: CaveatMutatorOperation.UpdateValue,\n      value: updatedCaveatValue,\n    };\n  }\n\n  return {\n    operation: CaveatMutatorOperation.RevokePermission,\n  };\n}\n"]}

package/dist/caip25Permission.d.cts

@@ -0,0 +1,131 @@
+import type { NetworkClientId } from "@metamask/network-controller";
+import type { PermissionSpecificationBuilder, EndowmentGetterParams, PermissionValidatorConstraint, EndowmentCaveatSpecificationConstraint } from "@metamask/permission-controller";
+import { CaveatMutatorOperation, PermissionType } from "@metamask/permission-controller";
+import type { CaipChainId, Json } from "@metamask/utils";
+import { type Hex, type NonEmptyArray } from "@metamask/utils";
+import { type ExternalScopeString, type InternalScopeObject, type InternalScopesObject } from "./scope/types.cjs";
+/**
+ * The CAIP-25 permission caveat value.
+ * This permission contains the required and optional scopes and session properties from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request that initiated the permission session.
+ * It also contains a boolean (isMultichainOrigin) indicating if the permission session is multichain, which may be needed to determine implicit permissioning.
+ */
+export type Caip25CaveatValue = {
+    requiredScopes: InternalScopesObject;
+    optionalScopes: InternalScopesObject;
+    sessionProperties?: Record<string, Json>;
+    isMultichainOrigin: boolean;
+};
+/**
+ * The name of the CAIP-25 permission caveat.
+ */
+export declare const Caip25CaveatType = "authorizedScopes";
+/**
+ * The target name of the CAIP-25 endowment permission.
+ */
+export declare const Caip25EndowmentPermissionName = "endowment:caip25";
+/**
+ * Creates a CAIP-25 permission caveat.
+ *
+ * @param value - The CAIP-25 permission caveat value.
+ * @returns The CAIP-25 permission caveat (now including the type).
+ */
+export declare const createCaip25Caveat: (value: Caip25CaveatValue) => {
+    type: string;
+    value: Caip25CaveatValue;
+};
+type Caip25EndowmentCaveatSpecificationBuilderOptions = {
+    findNetworkClientIdByChainId: (chainId: Hex) => NetworkClientId;
+    listAccounts: () => {
+        type: string;
+        address: Hex;
+    }[];
+    isNonEvmScopeSupported: (scope: CaipChainId) => boolean;
+    getNonEvmAccountAddresses: (scope: CaipChainId) => string[];
+};
+/**
+ * Calculates the difference between two provided CAIP-25 permission caveat values, but only considering a single scope property at a time.
+ *
+ * @param originalValue - The existing CAIP-25 permission caveat value.
+ * @param mergedValue - The result from merging existing and incoming CAIP-25 permission caveat values.
+ * @param scopeToDiff - The required or optional scopes from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request.
+ * @returns The difference between original and merged CAIP-25 permission caveat values.
+ */
+export declare function diffScopesForCaip25CaveatValue(originalValue: Caip25CaveatValue, mergedValue: Caip25CaveatValue, scopeToDiff: 'optionalScopes' | 'requiredScopes'): Caip25CaveatValue;
+/**
+ * Helper that returns a `authorizedScopes` CAIP-25 caveat specification
+ * that can be passed into the PermissionController constructor.
+ *
+ * @param options - The specification builder options.
+ * @param options.findNetworkClientIdByChainId - The hook for getting the networkClientId that serves a chainId.
+ * @param options.listAccounts - The hook for getting internalAccount objects for all evm accounts.
+ * @param options.isNonEvmScopeSupported - The hook that determines if an non EVM scopeString is supported.
+ * @param options.getNonEvmAccountAddresses - The hook that returns the supported CAIP-10 account addresses for a non EVM scope.
+ * @returns The specification for the `caip25` caveat.
+ */
+export declare const caip25CaveatBuilder: ({ findNetworkClientIdByChainId, listAccounts, isNonEvmScopeSupported, getNonEvmAccountAddresses, }: Caip25EndowmentCaveatSpecificationBuilderOptions) => EndowmentCaveatSpecificationConstraint & Required<Pick<EndowmentCaveatSpecificationConstraint, 'validator' | 'merger'>>;
+/**
+ * The `caip25` endowment specification builder. Passed to the
+ * `PermissionController` for constructing and validating the
+ * `endowment:caip25` permission.
+ */
+export declare const caip25EndowmentBuilder: Readonly<{
+    readonly targetName: "endowment:caip25";
+    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.Endowment, Record<never, never>, {
+        permissionType: PermissionType.Endowment;
+        targetName: typeof Caip25EndowmentPermissionName;
+        endowmentGetter: (_options?: EndowmentGetterParams) => null;
+        validator: PermissionValidatorConstraint;
+        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+    }>;
+}>;
+/**
+ * Factories that construct caveat mutator functions that are passed to
+ * PermissionController.updatePermissionsByCaveat.
+ */
+export declare const Caip25CaveatMutators: {
+    authorizedScopes: {
+        removeScope: typeof removeScope;
+        removeAccount: typeof removeAccount;
+    };
+};
+/**
+ * Removes the target account from the scope object.
+ *
+ * @param caip25CaveatValue - The CAIP-25 permission caveat value from which to remove the account (across all chain scopes).
+ * @param targetAddress - The address to remove from the scope object. Not a CAIP-10 formatted address because it will be removed across each chain scope.
+ * @returns The updated scope object.
+ */
+declare function removeAccount(caip25CaveatValue: Caip25CaveatValue, targetAddress: Hex): {
+    operation: CaveatMutatorOperation;
+    value?: undefined;
+} | {
+    operation: CaveatMutatorOperation;
+    value: Caip25CaveatValue;
+};
+/**
+ * Removes the target scope from the value arrays of the given
+ * `endowment:caip25` caveat. No-ops if the target scopeString is not in
+ * the existing scopes.
+ *
+ * @param caip25CaveatValue - The CAIP-25 permission caveat value to remove the scope from.
+ * @param targetScopeString - The scope that is being removed.
+ * @returns The updated CAIP-25 permission caveat value.
+ */
+declare function removeScope(caip25CaveatValue: Caip25CaveatValue, targetScopeString: ExternalScopeString): {
+    operation: CaveatMutatorOperation;
+    value?: undefined;
+} | {
+    operation: CaveatMutatorOperation;
+    value: {
+        requiredScopes: {
+            [k: string]: InternalScopeObject;
+        };
+        optionalScopes: {
+            [k: string]: InternalScopeObject;
+        };
+        sessionProperties?: Record<string, Json> | undefined;
+        isMultichainOrigin: boolean;
+    };
+};
+export {};
+//# sourceMappingURL=caip25Permission.d.cts.map

package/dist/caip25Permission.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caip25Permission.d.cts","sourceRoot":"","sources":["../src/caip25Permission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,qCAAqC;AACpE,OAAO,KAAK,EACV,8BAA8B,EAC9B,qBAAqB,EAErB,6BAA6B,EAE7B,sCAAsC,EACvC,wCAAwC;AACzC,OAAO,EACL,sBAAsB,EACtB,cAAc,EACf,wCAAwC;AACzC,OAAO,KAAK,EAAiB,WAAW,EAAE,IAAI,EAAE,wBAAwB;AACxE,OAAO,EAIL,KAAK,GAAG,EACR,KAAK,aAAa,EACnB,wBAAwB;AAMzB,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC1B,0BAAsB;AAEvB;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,oBAAoB,CAAC;IACrC,cAAc,EAAE,oBAAoB,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzC,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,6BAA6B,qBAAqB,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAW,iBAAiB;;;CAK1D,CAAC;AAEF,KAAK,gDAAgD,GAAG;IACtD,4BAA4B,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,eAAe,CAAC;IAChE,YAAY,EAAE,MAAM;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAE,EAAE,CAAC;IACrD,sBAAsB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC;IACxD,yBAAyB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,EAAE,CAAC;CAC7D,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,iBAAiB,EAChC,WAAW,EAAE,iBAAiB,EAC9B,WAAW,EAAE,gBAAgB,GAAG,gBAAgB,GAC/C,iBAAiB,CA2BnB;AA0BD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,uGAK7B,gDAAgD,KAAG,sCAAsC,GAC1F,SACE,KAAK,sCAAsC,EAAE,WAAW,GAAG,QAAQ,CAAC,CA2GvE,CAAC;AAuCF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;wBAzCjB,eAAe,SAAS;oBAC5B,oCAAoC;qCACnB,qBAAqB,KAAK,IAAI;mBAChD,6BAA6B;wBACxB,SAAS,cAAc,MAAM,CAAC,CAAC,GAAG,IAAI;;EAwC7C,CAAC;AAEZ;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;CAKhC,CAAC;AAgCF;;;;;;GAMG;AACH,iBAAS,aAAa,CACpB,iBAAiB,EAAE,iBAAiB,EACpC,aAAa,EAAE,GAAG;;;;;;EAoCnB;AAED;;;;;;;;GAQG;AACH,iBAAS,WAAW,CAClB,iBAAiB,EAAE,iBAAiB,EACpC,iBAAiB,EAAE,mBAAmB;;;;;;;;;;;;;;;EA+CvC"}

package/dist/caip25Permission.d.mts

@@ -0,0 +1,131 @@
+import type { NetworkClientId } from "@metamask/network-controller";
+import type { PermissionSpecificationBuilder, EndowmentGetterParams, PermissionValidatorConstraint, EndowmentCaveatSpecificationConstraint } from "@metamask/permission-controller";
+import { CaveatMutatorOperation, PermissionType } from "@metamask/permission-controller";
+import type { CaipChainId, Json } from "@metamask/utils";
+import { type Hex, type NonEmptyArray } from "@metamask/utils";
+import { type ExternalScopeString, type InternalScopeObject, type InternalScopesObject } from "./scope/types.mjs";
+/**
+ * The CAIP-25 permission caveat value.
+ * This permission contains the required and optional scopes and session properties from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request that initiated the permission session.
+ * It also contains a boolean (isMultichainOrigin) indicating if the permission session is multichain, which may be needed to determine implicit permissioning.
+ */
+export type Caip25CaveatValue = {
+    requiredScopes: InternalScopesObject;
+    optionalScopes: InternalScopesObject;
+    sessionProperties?: Record<string, Json>;
+    isMultichainOrigin: boolean;
+};
+/**
+ * The name of the CAIP-25 permission caveat.
+ */
+export declare const Caip25CaveatType = "authorizedScopes";
+/**
+ * The target name of the CAIP-25 endowment permission.
+ */
+export declare const Caip25EndowmentPermissionName = "endowment:caip25";
+/**
+ * Creates a CAIP-25 permission caveat.
+ *
+ * @param value - The CAIP-25 permission caveat value.
+ * @returns The CAIP-25 permission caveat (now including the type).
+ */
+export declare const createCaip25Caveat: (value: Caip25CaveatValue) => {
+    type: string;
+    value: Caip25CaveatValue;
+};
+type Caip25EndowmentCaveatSpecificationBuilderOptions = {
+    findNetworkClientIdByChainId: (chainId: Hex) => NetworkClientId;
+    listAccounts: () => {
+        type: string;
+        address: Hex;
+    }[];
+    isNonEvmScopeSupported: (scope: CaipChainId) => boolean;
+    getNonEvmAccountAddresses: (scope: CaipChainId) => string[];
+};
+/**
+ * Calculates the difference between two provided CAIP-25 permission caveat values, but only considering a single scope property at a time.
+ *
+ * @param originalValue - The existing CAIP-25 permission caveat value.
+ * @param mergedValue - The result from merging existing and incoming CAIP-25 permission caveat values.
+ * @param scopeToDiff - The required or optional scopes from the [CAIP-25](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-25.md) request.
+ * @returns The difference between original and merged CAIP-25 permission caveat values.
+ */
+export declare function diffScopesForCaip25CaveatValue(originalValue: Caip25CaveatValue, mergedValue: Caip25CaveatValue, scopeToDiff: 'optionalScopes' | 'requiredScopes'): Caip25CaveatValue;
+/**
+ * Helper that returns a `authorizedScopes` CAIP-25 caveat specification
+ * that can be passed into the PermissionController constructor.
+ *
+ * @param options - The specification builder options.
+ * @param options.findNetworkClientIdByChainId - The hook for getting the networkClientId that serves a chainId.
+ * @param options.listAccounts - The hook for getting internalAccount objects for all evm accounts.
+ * @param options.isNonEvmScopeSupported - The hook that determines if an non EVM scopeString is supported.
+ * @param options.getNonEvmAccountAddresses - The hook that returns the supported CAIP-10 account addresses for a non EVM scope.
+ * @returns The specification for the `caip25` caveat.
+ */
+export declare const caip25CaveatBuilder: ({ findNetworkClientIdByChainId, listAccounts, isNonEvmScopeSupported, getNonEvmAccountAddresses, }: Caip25EndowmentCaveatSpecificationBuilderOptions) => EndowmentCaveatSpecificationConstraint & Required<Pick<EndowmentCaveatSpecificationConstraint, 'validator' | 'merger'>>;
+/**
+ * The `caip25` endowment specification builder. Passed to the
+ * `PermissionController` for constructing and validating the
+ * `endowment:caip25` permission.
+ */
+export declare const caip25EndowmentBuilder: Readonly<{
+    readonly targetName: "endowment:caip25";
+    readonly specificationBuilder: PermissionSpecificationBuilder<PermissionType.Endowment, Record<never, never>, {
+        permissionType: PermissionType.Endowment;
+        targetName: typeof Caip25EndowmentPermissionName;
+        endowmentGetter: (_options?: EndowmentGetterParams) => null;
+        validator: PermissionValidatorConstraint;
+        allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+    }>;
+}>;
+/**
+ * Factories that construct caveat mutator functions that are passed to
+ * PermissionController.updatePermissionsByCaveat.
+ */
+export declare const Caip25CaveatMutators: {
+    authorizedScopes: {
+        removeScope: typeof removeScope;
+        removeAccount: typeof removeAccount;
+    };
+};
+/**
+ * Removes the target account from the scope object.
+ *
+ * @param caip25CaveatValue - The CAIP-25 permission caveat value from which to remove the account (across all chain scopes).
+ * @param targetAddress - The address to remove from the scope object. Not a CAIP-10 formatted address because it will be removed across each chain scope.
+ * @returns The updated scope object.
+ */
+declare function removeAccount(caip25CaveatValue: Caip25CaveatValue, targetAddress: Hex): {
+    operation: CaveatMutatorOperation;
+    value?: undefined;
+} | {
+    operation: CaveatMutatorOperation;
+    value: Caip25CaveatValue;
+};
+/**
+ * Removes the target scope from the value arrays of the given
+ * `endowment:caip25` caveat. No-ops if the target scopeString is not in
+ * the existing scopes.
+ *
+ * @param caip25CaveatValue - The CAIP-25 permission caveat value to remove the scope from.
+ * @param targetScopeString - The scope that is being removed.
+ * @returns The updated CAIP-25 permission caveat value.
+ */
+declare function removeScope(caip25CaveatValue: Caip25CaveatValue, targetScopeString: ExternalScopeString): {
+    operation: CaveatMutatorOperation;
+    value?: undefined;
+} | {
+    operation: CaveatMutatorOperation;
+    value: {
+        requiredScopes: {
+            [k: string]: InternalScopeObject;
+        };
+        optionalScopes: {
+            [k: string]: InternalScopeObject;
+        };
+        sessionProperties?: Record<string, Json> | undefined;
+        isMultichainOrigin: boolean;
+    };
+};
+export {};
+//# sourceMappingURL=caip25Permission.d.mts.map

package/dist/caip25Permission.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caip25Permission.d.mts","sourceRoot":"","sources":["../src/caip25Permission.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,qCAAqC;AACpE,OAAO,KAAK,EACV,8BAA8B,EAC9B,qBAAqB,EAErB,6BAA6B,EAE7B,sCAAsC,EACvC,wCAAwC;AACzC,OAAO,EACL,sBAAsB,EACtB,cAAc,EACf,wCAAwC;AACzC,OAAO,KAAK,EAAiB,WAAW,EAAE,IAAI,EAAE,wBAAwB;AACxE,OAAO,EAIL,KAAK,GAAG,EACR,KAAK,aAAa,EACnB,wBAAwB;AAMzB,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC1B,0BAAsB;AAEvB;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,oBAAoB,CAAC;IACrC,cAAc,EAAE,oBAAoB,CAAC;IACrC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACzC,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,6BAA6B,qBAAqB,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,UAAW,iBAAiB;;;CAK1D,CAAC;AAEF,KAAK,gDAAgD,GAAG;IACtD,4BAA4B,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,eAAe,CAAC;IAChE,YAAY,EAAE,MAAM;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,GAAG,CAAA;KAAE,EAAE,CAAC;IACrD,sBAAsB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC;IACxD,yBAAyB,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,EAAE,CAAC;CAC7D,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAC5C,aAAa,EAAE,iBAAiB,EAChC,WAAW,EAAE,iBAAiB,EAC9B,WAAW,EAAE,gBAAgB,GAAG,gBAAgB,GAC/C,iBAAiB,CA2BnB;AA0BD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,uGAK7B,gDAAgD,KAAG,sCAAsC,GAC1F,SACE,KAAK,sCAAsC,EAAE,WAAW,GAAG,QAAQ,CAAC,CA2GvE,CAAC;AAuCF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;wBAzCjB,eAAe,SAAS;oBAC5B,oCAAoC;qCACnB,qBAAqB,KAAK,IAAI;mBAChD,6BAA6B;wBACxB,SAAS,cAAc,MAAM,CAAC,CAAC,GAAG,IAAI;;EAwC7C,CAAC;AAEZ;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;CAKhC,CAAC;AAgCF;;;;;;GAMG;AACH,iBAAS,aAAa,CACpB,iBAAiB,EAAE,iBAAiB,EACpC,aAAa,EAAE,GAAG;;;;;;EAoCnB;AAED;;;;;;;;GAQG;AACH,iBAAS,WAAW,CAClB,iBAAiB,EAAE,iBAAiB,EACpC,iBAAiB,EAAE,mBAAmB;;;;;;;;;;;;;;;EA+CvC"}