@metamask-previews/permission-controller 9.0.2-preview-73f66baf → 9.0.2-preview-4e7f493

package/dist/{chunk-R66I7AKM.js → chunk-I3DJ23QH.js}

@@ -1,7 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 
-var _chunkJG74NEYVjs = require('./chunk-JG74NEYV.js');
+var _chunkRKDXFKNNjs = require('./chunk-RKDXFKNN.js');
 
 
 
@@ -10,7 +10,7 @@ var _chunkJG74NEYVjs = require('./chunk-JG74NEYV.js');
 var _chunkZH4MLSXXjs = require('./chunk-ZH4MLSXX.js');
 
 
-var _chunkAQ35E2HUjs = require('./chunk-AQ35E2HU.js');
+var _chunkVM4LI55Wjs = require('./chunk-VM4LI55W.js');
 
 
 
@@ -35,7 +35,17 @@ var _chunkAQ35E2HUjs = require('./chunk-AQ35E2HU.js');
 
 
 
-var _chunkU5LTEXSUjs = require('./chunk-U5LTEXSU.js');
+
+
+
+var _chunk3X6WO7UGjs = require('./chunk-3X6WO7UG.js');
+
+
+var _chunkPTE4672Ijs = require('./chunk-PTE4672I.js');
+
+
+
+var _chunkZ2XKIXLSjs = require('./chunk-Z2XKIXLS.js');
 
 // src/PermissionController.ts
 var _basecontroller = require('@metamask/base-controller');
@@ -63,15 +73,8 @@ var CaveatMutatorOperation = /* @__PURE__ */ ((CaveatMutatorOperation2) => {
   CaveatMutatorOperation2[CaveatMutatorOperation2["revokePermission"] = 3] = "revokePermission";
   return CaveatMutatorOperation2;
 })(CaveatMutatorOperation || {});
+var _expectGetCaveatMerger, expectGetCaveatMerger_fn, _applyGrantedPermissions, applyGrantedPermissions_fn, _mergeIncrementalPermissions, mergeIncrementalPermissions_fn, _mergePermission, mergePermission_fn, _mergeCaveat, mergeCaveat_fn, _handleApprovedPermissions, handleApprovedPermissions_fn;
 var PermissionController = class extends _basecontroller.BaseController {
-  /**
-   * The names of all JSON-RPC methods that will be ignored by the controller.
-   *
-   * @returns The names of all unrestricted JSON-RPC methods
-   */
-  get unrestrictedMethods() {
-    return this._unrestrictedMethods;
-  }
   /**
    * Constructs the PermissionController.
    *
@@ -106,6 +109,62 @@ var PermissionController = class extends _basecontroller.BaseController {
         ...state
       }
     });
+    /**
+     * Gets the merger function for the specified caveat. Throws if no
+     * merger exists.
+     *
+     * @param caveatType - The type of the caveat whose merger to get.
+     * @returns The caveat value merger function for the specified caveat type.
+     */
+    _chunkZ2XKIXLSjs.__privateAdd.call(void 0, this, _expectGetCaveatMerger);
+    _chunkZ2XKIXLSjs.__privateAdd.call(void 0, this, _applyGrantedPermissions);
+    /**
+     * Merges a set of incrementally requested permissions into the existing permissions of
+     * the requesting subject. The merge is a right-biased union, where the existing
+     * permissions are the left-hand side, and the incrementally requested permissions are
+     * the right-hand side.
+     *
+     * @param existingPermissions - The subject's existing permissions.
+     * @param incrementalRequestedPermissions - The requested permissions to merge.
+     * @returns The merged permissions and the resulting diff.
+     */
+    _chunkZ2XKIXLSjs.__privateAdd.call(void 0, this, _mergeIncrementalPermissions);
+    /**
+     * Performs a right-biased union between two permissions. The task of merging caveats
+     * of the same type between the two permissions is delegated to the corresponding
+     * caveat type's merger implementation.
+     *
+     * Throws if the left-hand and right-hand permissions both have a caveat whose
+     * specification does not provide a caveat value merger function.
+     *
+     * @param leftPermission - The left-hand permission to merge.
+     * @param rightPermission - The right-hand permission to merge.
+     * @returns The merged permission.
+     */
+    _chunkZ2XKIXLSjs.__privateAdd.call(void 0, this, _mergePermission);
+    /**
+     * Merges two caveats of the same type. The task of merging the values of the
+     * two caveats is delegated to the corresponding caveat type's merger implementation.
+     *
+     * @param leftCaveat - The left-hand caveat to merge.
+     * @param rightCaveat - The right-hand caveat to merge.
+     * @returns The merged caveat and the diff between the two caveats.
+     */
+    _chunkZ2XKIXLSjs.__privateAdd.call(void 0, this, _mergeCaveat);
+    /**
+     * Accepts a permissions request that has been approved by the user. This
+     * method should be called after the user has approved the request and the
+     * {@link ApprovalController} has resolved the user approval promise.
+     *
+     * @param options - Options bag.
+     * @param options.subject - The subject to grant permissions to.
+     * @param options.metadata - The metadata of the approved permissions request.
+     * @param options.preserveExistingPermissions - Whether to preserve the
+     * subject's existing permissions.
+     * @param options.approvedRequest - The approved permissions request to handle.
+     * @returns The granted permissions and request metadata.
+     */
+    _chunkZ2XKIXLSjs.__privateAdd.call(void 0, this, _handleApprovedPermissions);
     this._unrestrictedMethods = new Set(unrestrictedMethods);
     this._caveatSpecifications = _deepfreezestrict2.default.call(void 0, { ...caveatSpecifications });
     this.validatePermissionSpecifications(
@@ -116,7 +175,7 @@ var PermissionController = class extends _basecontroller.BaseController {
       ...permissionSpecifications
     });
     this.registerMessageHandlers();
-    this.createPermissionMiddleware = _chunkAQ35E2HUjs.getPermissionMiddlewareFactory.call(void 0, {
+    this.createPermissionMiddleware = _chunkVM4LI55Wjs.getPermissionMiddlewareFactory.call(void 0, {
       executeRestrictedMethod: this._executeRestrictedMethod.bind(this),
       getRestrictedMethod: this.getRestrictedMethod.bind(this),
       isUnrestrictedMethod: this.unrestrictedMethods.has.bind(
@@ -124,6 +183,14 @@ var PermissionController = class extends _basecontroller.BaseController {
       )
     });
   }
+  /**
+   * The names of all JSON-RPC methods that will be ignored by the controller.
+   *
+   * @returns The names of all unrestricted JSON-RPC methods
+   */
+  get unrestrictedMethods() {
+    return this._unrestrictedMethods;
+  }
   /**
    * Gets a permission specification.
    *
@@ -174,12 +241,12 @@ var PermissionController = class extends _basecontroller.BaseController {
         if (allowedCaveats) {
           allowedCaveats.forEach((caveatType) => {
             if (!_utils.hasProperty.call(void 0, caveatSpecifications, caveatType)) {
-              throw new (0, _chunkU5LTEXSUjs.UnrecognizedCaveatTypeError)(caveatType);
+              throw new (0, _chunk3X6WO7UGjs.UnrecognizedCaveatTypeError)(caveatType);
             }
             const specification = caveatSpecifications[caveatType];
-            const isRestrictedMethodCaveat = _chunkJG74NEYVjs.isRestrictedMethodCaveatSpecification.call(void 0, specification);
+            const isRestrictedMethodCaveat = _chunkRKDXFKNNjs.isRestrictedMethodCaveatSpecification.call(void 0, specification);
             if (permissionType === "RestrictedMethod" /* RestrictedMethod */ && !isRestrictedMethodCaveat || permissionType === "Endowment" /* Endowment */ && isRestrictedMethodCaveat) {
-              throw new (0, _chunkU5LTEXSUjs.CaveatSpecificationMismatchError)(
+              throw new (0, _chunk3X6WO7UGjs.CaveatSpecificationMismatchError)(
                 specification,
                 permissionType
               );
@@ -222,10 +289,18 @@ var PermissionController = class extends _basecontroller.BaseController {
       `${controllerName}:grantPermissions`,
       this.grantPermissions.bind(this)
     );
+    this.messagingSystem.registerActionHandler(
+      `${controllerName}:grantPermissionsIncremental`,
+      this.grantPermissionsIncremental.bind(this)
+    );
     this.messagingSystem.registerActionHandler(
       `${controllerName}:requestPermissions`,
       (subject, permissions) => this.requestPermissions(subject, permissions)
     );
+    this.messagingSystem.registerActionHandler(
+      `${controllerName}:requestPermissionsIncremental`,
+      (subject, permissions) => this.requestPermissionsIncremental(subject, permissions)
+    );
     this.messagingSystem.registerActionHandler(
       `${controllerName}:revokeAllPermissions`,
       (origin) => this.revokeAllPermissions(origin)
@@ -275,10 +350,10 @@ var PermissionController = class extends _basecontroller.BaseController {
    * target name.
    */
   getTypedPermissionSpecification(permissionType, targetName, requestingOrigin) {
-    const failureError = permissionType === "RestrictedMethod" /* RestrictedMethod */ ? _chunkU5LTEXSUjs.methodNotFound.call(void 0, 
+    const failureError = permissionType === "RestrictedMethod" /* RestrictedMethod */ ? _chunk3X6WO7UGjs.methodNotFound.call(void 0, 
       targetName,
       requestingOrigin ? { origin: requestingOrigin } : void 0
-    ) : new (0, _chunkU5LTEXSUjs.EndowmentPermissionDoesNotExistError)(
+    ) : new (0, _chunk3X6WO7UGjs.EndowmentPermissionDoesNotExistError)(
       targetName,
       requestingOrigin
     );
@@ -370,7 +445,7 @@ var PermissionController = class extends _basecontroller.BaseController {
   revokeAllPermissions(origin) {
     this.update((draftState) => {
       if (!draftState.subjects[origin]) {
-        throw new (0, _chunkU5LTEXSUjs.UnrecognizedSubjectError)(origin);
+        throw new (0, _chunk3X6WO7UGjs.UnrecognizedSubjectError)(origin);
       }
       delete draftState.subjects[origin];
     });
@@ -399,12 +474,12 @@ var PermissionController = class extends _basecontroller.BaseController {
     this.update((draftState) => {
       Object.keys(subjectsAndPermissions).forEach((origin) => {
         if (!_utils.hasProperty.call(void 0, draftState.subjects, origin)) {
-          throw new (0, _chunkU5LTEXSUjs.UnrecognizedSubjectError)(origin);
+          throw new (0, _chunk3X6WO7UGjs.UnrecognizedSubjectError)(origin);
         }
         subjectsAndPermissions[origin].forEach((target) => {
           const { permissions } = draftState.subjects[origin];
           if (!_utils.hasProperty.call(void 0, permissions, target)) {
-            throw new (0, _chunkU5LTEXSUjs.PermissionDoesNotExistError)(origin, target);
+            throw new (0, _chunk3X6WO7UGjs.PermissionDoesNotExistError)(origin, target);
           }
           this.deletePermission(draftState.subjects, origin, target);
         });
@@ -484,7 +559,7 @@ var PermissionController = class extends _basecontroller.BaseController {
   getCaveat(origin, target, caveatType) {
     const permission = this.getPermission(origin, target);
     if (!permission) {
-      throw new (0, _chunkU5LTEXSUjs.PermissionDoesNotExistError)(origin, target);
+      throw new (0, _chunk3X6WO7UGjs.PermissionDoesNotExistError)(origin, target);
     }
     return _chunkZH4MLSXXjs.findCaveat.call(void 0, permission, caveatType);
   }
@@ -509,7 +584,7 @@ var PermissionController = class extends _basecontroller.BaseController {
    */
   addCaveat(origin, target, caveatType, caveatValue) {
     if (this.hasCaveat(origin, target, caveatType)) {
-      throw new (0, _chunkU5LTEXSUjs.CaveatAlreadyExistsError)(origin, target, caveatType);
+      throw new (0, _chunk3X6WO7UGjs.CaveatAlreadyExistsError)(origin, target, caveatType);
     }
     this.setCaveat(origin, target, caveatType, caveatValue);
   }
@@ -533,7 +608,7 @@ var PermissionController = class extends _basecontroller.BaseController {
    */
   updateCaveat(origin, target, caveatType, caveatValue) {
     if (!this.hasCaveat(origin, target, caveatType)) {
-      throw new (0, _chunkU5LTEXSUjs.CaveatDoesNotExistError)(origin, target, caveatType);
+      throw new (0, _chunk3X6WO7UGjs.CaveatDoesNotExistError)(origin, target, caveatType);
     }
     this.setCaveat(origin, target, caveatType, caveatValue);
   }
@@ -559,11 +634,11 @@ var PermissionController = class extends _basecontroller.BaseController {
     this.update((draftState) => {
       const subject = draftState.subjects[origin];
       if (!subject) {
-        throw new (0, _chunkU5LTEXSUjs.UnrecognizedSubjectError)(origin);
+        throw new (0, _chunk3X6WO7UGjs.UnrecognizedSubjectError)(origin);
       }
       const permission = subject.permissions[target];
       if (!permission) {
-        throw new (0, _chunkU5LTEXSUjs.PermissionDoesNotExistError)(origin, target);
+        throw new (0, _chunk3X6WO7UGjs.PermissionDoesNotExistError)(origin, target);
       }
       const caveat = {
         type: caveatType,
@@ -670,10 +745,10 @@ var PermissionController = class extends _basecontroller.BaseController {
     this.update((draftState) => {
       const permission = draftState.subjects[origin]?.permissions[target];
       if (!permission) {
-        throw new (0, _chunkU5LTEXSUjs.PermissionDoesNotExistError)(origin, target);
+        throw new (0, _chunk3X6WO7UGjs.PermissionDoesNotExistError)(origin, target);
       }
       if (!permission.caveats) {
-        throw new (0, _chunkU5LTEXSUjs.CaveatDoesNotExistError)(origin, target, caveatType);
+        throw new (0, _chunk3X6WO7UGjs.CaveatDoesNotExistError)(origin, target, caveatType);
       }
       this.deleteCaveat(permission, caveatType, origin);
     });
@@ -692,7 +767,7 @@ var PermissionController = class extends _basecontroller.BaseController {
    */
   deleteCaveat(permission, caveatType, origin) {
     if (!permission.caveats) {
-      throw new (0, _chunkU5LTEXSUjs.CaveatDoesNotExistError)(
+      throw new (0, _chunk3X6WO7UGjs.CaveatDoesNotExistError)(
         origin,
         permission.parentCapability,
         caveatType
@@ -702,7 +777,7 @@ var PermissionController = class extends _basecontroller.BaseController {
       (existingCaveat) => existingCaveat.type === caveatType
     );
     if (caveatIndex === -1) {
-      throw new (0, _chunkU5LTEXSUjs.CaveatDoesNotExistError)(
+      throw new (0, _chunk3X6WO7UGjs.CaveatDoesNotExistError)(
         origin,
         permission.parentCapability,
         caveatType
@@ -750,10 +825,11 @@ var PermissionController = class extends _basecontroller.BaseController {
   }
   /**
    * Grants _approved_ permissions to the specified subject. Every permission and
-   * caveat is stringently validated – including by calling every specification
-   * validator – and an error is thrown if any validation fails.
+   * caveat is stringently validated—including by calling their specification
+   * validators—and an error is thrown if validation fails.
    *
-   * ATTN: This method does **not** prompt the user for approval.
+   * ATTN: This method does **not** prompt the user for approval. User consent must
+   * first be obtained through some other means.
    *
    * @see {@link PermissionController.requestPermissions} For initiating a
    * permissions request requiring user approval.
@@ -765,7 +841,7 @@ var PermissionController = class extends _basecontroller.BaseController {
    * @param options.preserveExistingPermissions - Whether to preserve the
    * subject's existing permissions.
    * @param options.subject - The subject to grant permissions to.
-   * @returns The granted permissions.
+   * @returns The subject's new permission state. It may or may not have changed.
    */
   grantPermissions({
     approvedPermissions,
@@ -773,53 +849,44 @@ var PermissionController = class extends _basecontroller.BaseController {
     preserveExistingPermissions = true,
     subject
   }) {
-    const { origin } = subject;
-    if (!origin || typeof origin !== "string") {
-      throw new (0, _chunkU5LTEXSUjs.InvalidSubjectIdentifierError)(origin);
-    }
-    const permissions = preserveExistingPermissions ? {
-      ...this.getPermissions(origin)
-    } : {};
-    for (const [requestedTarget, approvedPermission] of Object.entries(
-      approvedPermissions
-    )) {
-      if (!this.targetExists(requestedTarget)) {
-        throw _chunkU5LTEXSUjs.methodNotFound.call(void 0, requestedTarget);
-      }
-      if (approvedPermission.parentCapability !== void 0 && requestedTarget !== approvedPermission.parentCapability) {
-        throw new (0, _chunkU5LTEXSUjs.InvalidApprovedPermissionError)(
-          origin,
-          requestedTarget,
-          approvedPermission
-        );
-      }
-      const targetName = requestedTarget;
-      const specification = this.getPermissionSpecification(targetName);
-      const caveats = this.constructCaveats(
-        origin,
-        targetName,
-        approvedPermission.caveats
-      );
-      const permissionOptions = {
-        caveats,
-        invoker: origin,
-        target: targetName
-      };
-      let permission;
-      if (specification.factory) {
-        permission = specification.factory(permissionOptions, requestData);
-        this.validatePermission(specification, permission, origin);
-      } else {
-        permission = _chunkZH4MLSXXjs.constructPermission.call(void 0, permissionOptions);
-        this.validatePermission(specification, permission, origin, {
-          invokePermissionValidator: true,
-          performCaveatValidation: false
-        });
-      }
-      permissions[targetName] = permission;
-    }
-    this.setValidatedPermissions(origin, permissions);
-    return permissions;
+    return _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _applyGrantedPermissions, applyGrantedPermissions_fn).call(this, {
+      approvedPermissions,
+      subject,
+      mergePermissions: false,
+      preserveExistingPermissions,
+      requestData
+    });
+  }
+  /**
+   * Incrementally grants _approved_ permissions to the specified subject. Every
+   * permission and caveat is stringently validated—including by calling their
+   * specification validators—and an error is thrown if validation fails.
+   *
+   * ATTN: This method does **not** prompt the user for approval. User consent must
+   * first be obtained through some other means.
+   *
+   * @see {@link PermissionController.requestPermissionsIncremental} For initiating
+   * an incremental permissions request requiring user approval.
+   * @param options - Options bag.
+   * @param options.approvedPermissions - The requested permissions approved by
+   * the user.
+   * @param options.requestData - Permission request data. Passed to permission
+   * factory functions.
+   * @param options.subject - The subject to grant permissions to.
+   * @returns The subject's new permission state. It may or may not have changed.
+   */
+  grantPermissionsIncremental({
+    approvedPermissions,
+    requestData,
+    subject
+  }) {
+    return _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _applyGrantedPermissions, applyGrantedPermissions_fn).call(this, {
+      approvedPermissions,
+      subject,
+      mergePermissions: true,
+      preserveExistingPermissions: true,
+      requestData
+    });
   }
   /**
    * Validates the specified permission by:
@@ -853,13 +920,13 @@ var PermissionController = class extends _basecontroller.BaseController {
         origin
       );
       if (!metadata || metadata.subjectType === null || !specification.subjectTypes.includes(metadata.subjectType)) {
-        throw specification.permissionType === "RestrictedMethod" /* RestrictedMethod */ ? _chunkU5LTEXSUjs.methodNotFound.call(void 0, targetName, { origin }) : new (0, _chunkU5LTEXSUjs.EndowmentPermissionDoesNotExistError)(targetName, origin);
+        throw specification.permissionType === "RestrictedMethod" /* RestrictedMethod */ ? _chunk3X6WO7UGjs.methodNotFound.call(void 0, targetName, { origin }) : new (0, _chunk3X6WO7UGjs.EndowmentPermissionDoesNotExistError)(targetName, origin);
       }
     }
     if (_utils.hasProperty.call(void 0, permission, "caveats")) {
       const { caveats } = permission;
       if (caveats !== null && !(Array.isArray(caveats) && caveats.length > 0)) {
-        throw new (0, _chunkU5LTEXSUjs.InvalidCaveatsPropertyError)(origin, targetName, caveats);
+        throw new (0, _chunk3X6WO7UGjs.InvalidCaveatsPropertyError)(origin, targetName, caveats);
       }
       const seenCaveatTypes = /* @__PURE__ */ new Set();
       caveats?.forEach((caveat) => {
@@ -867,10 +934,10 @@ var PermissionController = class extends _basecontroller.BaseController {
           this.validateCaveat(caveat, origin, targetName);
         }
         if (!allowedCaveats?.includes(caveat.type)) {
-          throw new (0, _chunkU5LTEXSUjs.ForbiddenCaveatError)(caveat.type, origin, targetName);
+          throw new (0, _chunk3X6WO7UGjs.ForbiddenCaveatError)(caveat.type, origin, targetName);
         }
         if (seenCaveatTypes.has(caveat.type)) {
-          throw new (0, _chunkU5LTEXSUjs.DuplicateCaveatError)(caveat.type, origin, targetName);
+          throw new (0, _chunk3X6WO7UGjs.DuplicateCaveatError)(caveat.type, origin, targetName);
         }
         seenCaveatTypes.add(caveat.type);
       });
@@ -931,30 +998,32 @@ var PermissionController = class extends _basecontroller.BaseController {
    */
   validateCaveat(caveat, origin, target) {
     if (!_controllerutils.isPlainObject.call(void 0, caveat)) {
-      throw new (0, _chunkU5LTEXSUjs.InvalidCaveatError)(caveat, origin, target);
+      throw new (0, _chunk3X6WO7UGjs.InvalidCaveatError)(caveat, origin, target);
     }
     if (Object.keys(caveat).length !== 2) {
-      throw new (0, _chunkU5LTEXSUjs.InvalidCaveatFieldsError)(caveat, origin, target);
+      throw new (0, _chunk3X6WO7UGjs.InvalidCaveatFieldsError)(caveat, origin, target);
     }
     if (typeof caveat.type !== "string") {
-      throw new (0, _chunkU5LTEXSUjs.InvalidCaveatTypeError)(caveat, origin, target);
+      throw new (0, _chunk3X6WO7UGjs.InvalidCaveatTypeError)(caveat, origin, target);
     }
     const specification = this.getCaveatSpecification(caveat.type);
     if (!specification) {
-      throw new (0, _chunkU5LTEXSUjs.UnrecognizedCaveatTypeError)(caveat.type, origin, target);
+      throw new (0, _chunk3X6WO7UGjs.UnrecognizedCaveatTypeError)(caveat.type, origin, target);
     }
     if (!_utils.hasProperty.call(void 0, caveat, "value") || caveat.value === void 0) {
-      throw new (0, _chunkU5LTEXSUjs.CaveatMissingValueError)(caveat, origin, target);
+      throw new (0, _chunk3X6WO7UGjs.CaveatMissingValueError)(caveat, origin, target);
     }
     if (!_controllerutils.isValidJson.call(void 0, caveat.value)) {
-      throw new (0, _chunkU5LTEXSUjs.CaveatInvalidJsonError)(caveat, origin, target);
+      throw new (0, _chunk3X6WO7UGjs.CaveatInvalidJsonError)(caveat, origin, target);
     }
     specification.validator?.(caveat, origin, target);
   }
   /**
-   * Initiates a permission request that requires user approval. This should
-   * always be used to grant additional permissions to a subject, unless user
-   * approval has been obtained through some other means.
+   * Initiates a permission request that requires user approval.
+   *
+   * Either this or {@link PermissionController.requestPermissionsIncremental}
+   * should always be used to grant additional permissions to a subject,
+   * unless user approval has been obtained through some other means.
    *
    * Permissions are validated at every step of the approval process, and this
    * method will reject if validation fails.
@@ -988,36 +1057,85 @@ var PermissionController = class extends _basecontroller.BaseController {
       permissions: requestedPermissions
     };
     const approvedRequest = await this.requestUserApproval(permissionsRequest);
-    const { permissions: approvedPermissions, ...requestData } = approvedRequest;
-    const sideEffects = this.getSideEffects(approvedPermissions);
-    if (Object.values(sideEffects.permittedHandlers).length > 0) {
-      const sideEffectsData = await this.executeSideEffects(
-        sideEffects,
-        approvedRequest
-      );
-      const mappedData = Object.keys(sideEffects.permittedHandlers).reduce(
-        (acc, permission, i) => ({ [permission]: sideEffectsData[i], ...acc }),
-        {}
-      );
-      return [
-        this.grantPermissions({
-          subject,
-          approvedPermissions,
-          preserveExistingPermissions,
-          requestData
-        }),
-        { data: mappedData, ...metadata }
-      ];
+    return await _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _handleApprovedPermissions, handleApprovedPermissions_fn).call(this, {
+      subject,
+      metadata,
+      preserveExistingPermissions,
+      approvedRequest
+    });
+  }
+  /**
+   * Initiates an incremental permission request that prompts for user approval.
+   * Incremental permission requests allow the caller to replace existing and/or
+   * add brand new permissions and caveats for the specified subject.
+   *
+   * Incremental permission request are merged with the subject's existing permissions
+   * through a right-biased union, where the incremental permission are the right-hand
+   * side of the merger. If both sides of the merger specify the same caveats for a
+   * given permission, the caveats are merged using their specification's caveat value
+   * merger property.
+   *
+   * Either this or {@link PermissionController.requestPermissions} should
+   * always be used to grant additional permissions to a subject, unless user
+   * approval has been obtained through some other means.
+   *
+   * Permissions are validated at every step of the approval process, and this
+   * method will reject if validation fails.
+   *
+   * @see {@link ApprovalController} For the user approval logic.
+   * @see {@link PermissionController.acceptPermissionsRequest} For the method
+   * that _accepts_ the request and resolves the user approval promise.
+   * @see {@link PermissionController.rejectPermissionsRequest} For the method
+   * that _rejects_ the request and the user approval promise.
+   * @param subject - The grantee subject.
+   * @param requestedPermissions - The requested permissions.
+   * @param options - Additional options.
+   * @param options.id - The id of the permissions request. Defaults to a unique
+   * id.
+   * @param options.metadata - Additional metadata about the permission request.
+   * @returns The granted permissions and request metadata.
+   */
+  async requestPermissionsIncremental(subject, requestedPermissions, options = {}) {
+    const { origin } = subject;
+    const { id = _nanoid.nanoid.call(void 0, ) } = options;
+    this.validateRequestedPermissions(origin, requestedPermissions);
+    const currentPermissions = this.getPermissions(origin) ?? {};
+    const [newPermissions, permissionDiffMap] = _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _mergeIncrementalPermissions, mergeIncrementalPermissions_fn).call(this, currentPermissions, requestedPermissions);
+    if (newPermissions === void 0 || permissionDiffMap === void 0) {
+      return [];
     }
-    return [
-      this.grantPermissions({
-        subject,
-        approvedPermissions,
-        preserveExistingPermissions,
-        requestData
-      }),
-      metadata
-    ];
+    try {
+      this.validateRequestedPermissions(origin, newPermissions);
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new (0, _chunk3X6WO7UGjs.InvalidMergedPermissionsError)(
+          origin,
+          error,
+          permissionDiffMap
+        );
+      }
+      throw _chunk3X6WO7UGjs.internalError.call(void 0, "Unrecognized error type", { error });
+    }
+    const metadata = {
+      ...options.metadata,
+      id,
+      origin
+    };
+    const permissionsRequest = {
+      metadata,
+      permissions: newPermissions,
+      diff: {
+        currentPermissions,
+        permissionDiffMap
+      }
+    };
+    const approvedRequest = await this.requestUserApproval(permissionsRequest);
+    return await _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _handleApprovedPermissions, handleApprovedPermissions_fn).call(this, {
+      subject,
+      metadata,
+      preserveExistingPermissions: false,
+      approvedRequest
+    });
   }
   /**
    * Validates requested permissions. Throws if validation fails.
@@ -1036,13 +1154,13 @@ var PermissionController = class extends _basecontroller.BaseController {
    */
   validateRequestedPermissions(origin, requestedPermissions) {
     if (!_controllerutils.isPlainObject.call(void 0, requestedPermissions)) {
-      throw _chunkU5LTEXSUjs.invalidParams.call(void 0, {
+      throw _chunk3X6WO7UGjs.invalidParams.call(void 0, {
         message: `Requested permissions for origin "${origin}" is not a plain object.`,
         data: { origin, requestedPermissions }
       });
     }
     if (Object.keys(requestedPermissions).length === 0) {
-      throw _chunkU5LTEXSUjs.invalidParams.call(void 0, {
+      throw _chunk3X6WO7UGjs.invalidParams.call(void 0, {
         message: `Permissions request for origin "${origin}" contains no permissions.`,
         data: { requestedPermissions }
       });
@@ -1050,10 +1168,10 @@ var PermissionController = class extends _basecontroller.BaseController {
     for (const targetName of Object.keys(requestedPermissions)) {
       const permission = requestedPermissions[targetName];
       if (!this.targetExists(targetName)) {
-        throw _chunkU5LTEXSUjs.methodNotFound.call(void 0, targetName, { origin, requestedPermissions });
+        throw _chunk3X6WO7UGjs.methodNotFound.call(void 0, targetName, { origin, requestedPermissions });
       }
       if (!_controllerutils.isPlainObject.call(void 0, permission) || permission.parentCapability !== void 0 && targetName !== permission.parentCapability) {
-        throw _chunkU5LTEXSUjs.invalidParams.call(void 0, {
+        throw _chunk3X6WO7UGjs.invalidParams.call(void 0, {
           message: `Permissions request for origin "${origin}" contains invalid requested permission(s).`,
           data: { origin, requestedPermissions }
         });
@@ -1143,14 +1261,14 @@ var PermissionController = class extends _basecontroller.BaseController {
             failureHandlersList.map((failureHandler) => failureHandler(params))
           );
         } catch (error) {
-          throw _chunkU5LTEXSUjs.internalError.call(void 0, "Unexpected error in side-effects", { error });
+          throw _chunk3X6WO7UGjs.internalError.call(void 0, "Unexpected error in side-effects", { error });
         }
       }
       const reasons = rejectedHandlers.map((handler) => handler.reason);
       reasons.forEach((reason) => {
         console.error(reason);
       });
-      throw reasons.length > 1 ? _chunkU5LTEXSUjs.internalError.call(void 0, 
+      throw reasons.length > 1 ? _chunk3X6WO7UGjs.internalError.call(void 0, 
         "Multiple errors occurred during side-effects execution",
         { errors: reasons }
       ) : reasons[0];
@@ -1175,7 +1293,7 @@ var PermissionController = class extends _basecontroller.BaseController {
   validateApprovedPermissions(approvedRequest, originalMetadata) {
     const { id, origin } = originalMetadata;
     if (!_controllerutils.isPlainObject.call(void 0, approvedRequest) || !_controllerutils.isPlainObject.call(void 0, approvedRequest.metadata)) {
-      throw _chunkU5LTEXSUjs.internalError.call(void 0, 
+      throw _chunk3X6WO7UGjs.internalError.call(void 0, 
         `Approved permissions request for subject "${origin}" is invalid.`,
         { data: { approvedRequest } }
       );
@@ -1185,13 +1303,13 @@ var PermissionController = class extends _basecontroller.BaseController {
       permissions
     } = approvedRequest;
     if (newId !== id) {
-      throw _chunkU5LTEXSUjs.internalError.call(void 0, 
+      throw _chunk3X6WO7UGjs.internalError.call(void 0, 
         `Approved permissions request for subject "${origin}" mutated its id.`,
         { originalId: id, mutatedId: newId }
       );
     }
     if (newOrigin !== origin) {
-      throw _chunkU5LTEXSUjs.internalError.call(void 0, 
+      throw _chunk3X6WO7UGjs.internalError.call(void 0, 
         `Approved permissions request for subject "${origin}" mutated its origin.`,
         { originalOrigin: origin, mutatedOrigin: newOrigin }
       );
@@ -1200,12 +1318,12 @@ var PermissionController = class extends _basecontroller.BaseController {
       this.validateRequestedPermissions(origin, permissions);
     } catch (error) {
       if (error instanceof Error) {
-        throw _chunkU5LTEXSUjs.internalError.call(void 0, 
+        throw _chunk3X6WO7UGjs.internalError.call(void 0, 
           `Invalid approved permissions request: ${error.message}`,
           error instanceof _rpcerrors.JsonRpcError ? error.data : void 0
         );
       }
-      throw _chunkU5LTEXSUjs.internalError.call(void 0, "Unrecognized error type", { error });
+      throw _chunk3X6WO7UGjs.internalError.call(void 0, "Unrecognized error type", { error });
     }
   }
   /**
@@ -1217,12 +1335,12 @@ var PermissionController = class extends _basecontroller.BaseController {
   async acceptPermissionsRequest(request) {
     const { id } = request.metadata;
     if (!this.hasApprovalRequest({ id })) {
-      throw new (0, _chunkU5LTEXSUjs.PermissionsRequestNotFoundError)(id);
+      throw new (0, _chunk3X6WO7UGjs.PermissionsRequestNotFoundError)(id);
     }
     if (Object.keys(request.permissions).length === 0) {
       this._rejectPermissionsRequest(
         id,
-        _chunkU5LTEXSUjs.invalidParams.call(void 0, {
+        _chunk3X6WO7UGjs.invalidParams.call(void 0, {
           message: "Must request at least one permission."
         })
       );
@@ -1247,9 +1365,9 @@ var PermissionController = class extends _basecontroller.BaseController {
    */
   async rejectPermissionsRequest(id) {
     if (!this.hasApprovalRequest({ id })) {
-      throw new (0, _chunkU5LTEXSUjs.PermissionsRequestNotFoundError)(id);
+      throw new (0, _chunk3X6WO7UGjs.PermissionsRequestNotFoundError)(id);
     }
-    this._rejectPermissionsRequest(id, _chunkU5LTEXSUjs.userRejectedRequest.call(void 0, ));
+    this._rejectPermissionsRequest(id, _chunk3X6WO7UGjs.userRejectedRequest.call(void 0, ));
   }
   /**
    * Checks whether the {@link ApprovalController} has a particular permissions
@@ -1296,7 +1414,7 @@ var PermissionController = class extends _basecontroller.BaseController {
    */
   async getEndowments(origin, targetName, requestData) {
     if (!this.hasPermission(origin, targetName)) {
-      throw _chunkU5LTEXSUjs.unauthorized.call(void 0, { data: { origin, targetName } });
+      throw _chunk3X6WO7UGjs.unauthorized.call(void 0, { data: { origin, targetName } });
     }
     return this.getTypedPermissionSpecification(
       "Endowment" /* Endowment */,
@@ -1366,18 +1484,196 @@ var PermissionController = class extends _basecontroller.BaseController {
     const { origin } = subject;
     const permission = this.getPermission(origin, method);
     if (!permission) {
-      throw _chunkU5LTEXSUjs.unauthorized.call(void 0, { data: { origin, method } });
+      throw _chunk3X6WO7UGjs.unauthorized.call(void 0, { data: { origin, method } });
     }
-    return _chunkJG74NEYVjs.decorateWithCaveats.call(void 0, 
+    return _chunkRKDXFKNNjs.decorateWithCaveats.call(void 0, 
       methodImplementation,
       permission,
       this._caveatSpecifications
     )({ method, params, context: { origin } });
   }
 };
+_expectGetCaveatMerger = new WeakSet();
+expectGetCaveatMerger_fn = function(caveatType) {
+  const { merger } = this.getCaveatSpecification(caveatType);
+  if (merger === void 0) {
+    throw new (0, _chunk3X6WO7UGjs.CaveatMergerDoesNotExistError)(caveatType);
+  }
+  return merger;
+};
+_applyGrantedPermissions = new WeakSet();
+applyGrantedPermissions_fn = function({
+  approvedPermissions,
+  subject,
+  mergePermissions,
+  preserveExistingPermissions,
+  requestData
+}) {
+  const { origin } = subject;
+  if (!origin || typeof origin !== "string") {
+    throw new (0, _chunk3X6WO7UGjs.InvalidSubjectIdentifierError)(origin);
+  }
+  const permissions = preserveExistingPermissions ? {
+    ...this.getPermissions(origin)
+  } : {};
+  for (const [requestedTarget, approvedPermission] of Object.entries(
+    approvedPermissions
+  )) {
+    if (!this.targetExists(requestedTarget)) {
+      throw _chunk3X6WO7UGjs.methodNotFound.call(void 0, requestedTarget);
+    }
+    if (approvedPermission.parentCapability !== void 0 && requestedTarget !== approvedPermission.parentCapability) {
+      throw new (0, _chunk3X6WO7UGjs.InvalidApprovedPermissionError)(
+        origin,
+        requestedTarget,
+        approvedPermission
+      );
+    }
+    const targetName = requestedTarget;
+    const specification = this.getPermissionSpecification(targetName);
+    const caveats = this.constructCaveats(
+      origin,
+      targetName,
+      approvedPermission.caveats
+    );
+    const permissionOptions = {
+      caveats,
+      invoker: origin,
+      target: targetName
+    };
+    let permission;
+    let performCaveatValidation = true;
+    if (specification.factory) {
+      permission = specification.factory(permissionOptions, requestData);
+    } else {
+      permission = _chunkZH4MLSXXjs.constructPermission.call(void 0, permissionOptions);
+      performCaveatValidation = false;
+    }
+    if (mergePermissions) {
+      permission = _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _mergePermission, mergePermission_fn).call(this, permissions[targetName], permission)[0];
+    }
+    this.validatePermission(specification, permission, origin, {
+      invokePermissionValidator: true,
+      performCaveatValidation
+    });
+    permissions[targetName] = permission;
+  }
+  this.setValidatedPermissions(origin, permissions);
+  return permissions;
+};
+_mergeIncrementalPermissions = new WeakSet();
+mergeIncrementalPermissions_fn = function(existingPermissions, incrementalRequestedPermissions) {
+  const permissionDiffMap = {};
+  const newPermissions = _immer.produce.call(void 0, 
+    existingPermissions,
+    (draftExistingPermissions) => {
+      const leftPermissions = draftExistingPermissions;
+      Object.entries(incrementalRequestedPermissions).forEach(
+        ([targetName, rightPermission]) => {
+          const leftPermission = leftPermissions[targetName];
+          const [newPermission, caveatsDiff] = _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _mergePermission, mergePermission_fn).call(this, leftPermission ?? {}, rightPermission);
+          if (leftPermission === void 0 || Object.keys(caveatsDiff).length > 0) {
+            leftPermissions[targetName] = newPermission;
+            permissionDiffMap[targetName] = caveatsDiff;
+          }
+        }
+      );
+    }
+  );
+  if (Object.keys(permissionDiffMap).length === 0) {
+    return [];
+  }
+  return [newPermissions, permissionDiffMap];
+};
+_mergePermission = new WeakSet();
+mergePermission_fn = function(leftPermission, rightPermission) {
+  const { caveatPairs, leftUniqueCaveats, rightUniqueCaveats } = _chunkPTE4672Ijs.collectUniqueAndPairedCaveats.call(void 0, leftPermission, rightPermission);
+  const [mergedCaveats, caveatDiffMap] = caveatPairs.reduce(
+    ([caveats, diffMap], [leftCaveat, rightCaveat]) => {
+      const [newCaveat, diff] = _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _mergeCaveat, mergeCaveat_fn).call(this, leftCaveat, rightCaveat);
+      if (newCaveat !== void 0 && diff !== void 0) {
+        caveats.push(newCaveat);
+        diffMap[newCaveat.type] = diff;
+      } else {
+        caveats.push(leftCaveat);
+      }
+      return [caveats, diffMap];
+    },
+    [[], {}]
+  );
+  const mergedRightUniqueCaveats = rightUniqueCaveats.map((caveat) => {
+    const [newCaveat, diff] = _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _mergeCaveat, mergeCaveat_fn).call(this, void 0, caveat);
+    caveatDiffMap[newCaveat.type] = diff;
+    return newCaveat;
+  });
+  const allCaveats = [
+    ...mergedCaveats,
+    ...leftUniqueCaveats,
+    ...mergedRightUniqueCaveats
+  ];
+  const newPermission = {
+    ...leftPermission,
+    ...rightPermission,
+    ...allCaveats.length > 0 ? { caveats: allCaveats } : {}
+  };
+  return [newPermission, caveatDiffMap];
+};
+_mergeCaveat = new WeakSet();
+mergeCaveat_fn = function(leftCaveat, rightCaveat) {
+  if (leftCaveat !== void 0 && leftCaveat.type !== rightCaveat.type) {
+    throw new (0, _chunk3X6WO7UGjs.CaveatMergeTypeMismatchError)(leftCaveat.type, rightCaveat.type);
+  }
+  const merger = _chunkZ2XKIXLSjs.__privateMethod.call(void 0, this, _expectGetCaveatMerger, expectGetCaveatMerger_fn).call(this, rightCaveat.type);
+  if (leftCaveat === void 0) {
+    return [
+      {
+        ...rightCaveat
+      },
+      rightCaveat.value
+    ];
+  }
+  const [newValue, diff] = merger(leftCaveat.value, rightCaveat.value);
+  return newValue !== void 0 && diff !== void 0 ? [
+    {
+      type: rightCaveat.type,
+      value: newValue
+    },
+    diff
+  ] : [];
+};
+_handleApprovedPermissions = new WeakSet();
+handleApprovedPermissions_fn = async function({
+  subject,
+  metadata,
+  preserveExistingPermissions,
+  approvedRequest
+}) {
+  const { permissions: approvedPermissions, ...requestData } = approvedRequest;
+  const approvedMetadata = { ...metadata };
+  const sideEffects = this.getSideEffects(approvedPermissions);
+  if (Object.values(sideEffects.permittedHandlers).length > 0) {
+    const sideEffectsData = await this.executeSideEffects(
+      sideEffects,
+      approvedRequest
+    );
+    approvedMetadata.data = Object.keys(sideEffects.permittedHandlers).reduce(
+      (acc, permission, i) => ({ [permission]: sideEffectsData[i], ...acc }),
+      {}
+    );
+  }
+  return [
+    this.grantPermissions({
+      subject,
+      approvedPermissions,
+      preserveExistingPermissions,
+      requestData
+    }),
+    approvedMetadata
+  ];
+};
 
 
 
 
 exports.CaveatMutatorOperation = CaveatMutatorOperation; exports.PermissionController = PermissionController;
-//# sourceMappingURL=chunk-R66I7AKM.js.map
+//# sourceMappingURL=chunk-I3DJ23QH.js.map