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

package/dist/{chunk-MCDOYEJY.mjs → chunk-4B6NOD2D.mjs}

@@ -1,7 +1,7 @@
 import {
   decorateWithCaveats,
   isRestrictedMethodCaveatSpecification
-} from "./chunk-DRXP4C4H.mjs";
+} from "./chunk-RJKSCKTD.mjs";
 import {
   PermissionType,
   constructPermission,
@@ -10,11 +10,13 @@ import {
 } from "./chunk-HYMS7IGB.mjs";
 import {
   getPermissionMiddlewareFactory
-} from "./chunk-N4KQ2BHF.mjs";
+} from "./chunk-RXC2KFRK.mjs";
 import {
   CaveatAlreadyExistsError,
   CaveatDoesNotExistError,
   CaveatInvalidJsonError,
+  CaveatMergeTypeMismatchError,
+  CaveatMergerDoesNotExistError,
   CaveatMissingValueError,
   CaveatSpecificationMismatchError,
   DuplicateCaveatError,
@@ -25,6 +27,7 @@ import {
   InvalidCaveatFieldsError,
   InvalidCaveatTypeError,
   InvalidCaveatsPropertyError,
+  InvalidMergedPermissionsError,
   InvalidSubjectIdentifierError,
   PermissionDoesNotExistError,
   PermissionsRequestNotFoundError,
@@ -35,7 +38,14 @@ import {
   methodNotFound,
   unauthorized,
   userRejectedRequest
-} from "./chunk-FEXS6SJF.mjs";
+} from "./chunk-AZUM6CBY.mjs";
+import {
+  collectUniqueAndPairedCaveats
+} from "./chunk-3R56AY2L.mjs";
+import {
+  __privateAdd,
+  __privateMethod
+} from "./chunk-2L4QPE5A.mjs";
 
 // src/PermissionController.ts
 import { BaseController } from "@metamask/base-controller";
@@ -47,7 +57,7 @@ import {
 import { JsonRpcError } from "@metamask/rpc-errors";
 import { hasProperty } from "@metamask/utils";
 import deepFreeze from "deep-freeze-strict";
-import { castDraft } from "immer";
+import { castDraft, produce as immerProduce } from "immer";
 import { nanoid } from "nanoid";
 var controllerName = "PermissionController";
 function getStateMetadata() {
@@ -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 {
-  /**
-   * 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 {
         ...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.
+     */
+    __privateAdd(this, _expectGetCaveatMerger);
+    __privateAdd(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.
+     */
+    __privateAdd(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.
+     */
+    __privateAdd(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.
+     */
+    __privateAdd(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.
+     */
+    __privateAdd(this, _handleApprovedPermissions);
     this._unrestrictedMethods = new Set(unrestrictedMethods);
     this._caveatSpecifications = deepFreeze({ ...caveatSpecifications });
     this.validatePermissionSpecifications(
@@ -124,6 +183,14 @@ var PermissionController = class extends 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.
    *
@@ -222,10 +289,18 @@ var PermissionController = class extends 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)
@@ -750,10 +825,11 @@ var PermissionController = class extends 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 {
    * @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 {
     preserveExistingPermissions = true,
     subject
   }) {
-    const { origin } = subject;
-    if (!origin || typeof origin !== "string") {
-      throw new InvalidSubjectIdentifierError(origin);
-    }
-    const permissions = preserveExistingPermissions ? {
-      ...this.getPermissions(origin)
-    } : {};
-    for (const [requestedTarget, approvedPermission] of Object.entries(
-      approvedPermissions
-    )) {
-      if (!this.targetExists(requestedTarget)) {
-        throw methodNotFound(requestedTarget);
-      }
-      if (approvedPermission.parentCapability !== void 0 && requestedTarget !== approvedPermission.parentCapability) {
-        throw new 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 = constructPermission(permissionOptions);
-        this.validatePermission(specification, permission, origin, {
-          invokePermissionValidator: true,
-          performCaveatValidation: false
-        });
-      }
-      permissions[targetName] = permission;
-    }
-    this.setValidatedPermissions(origin, permissions);
-    return permissions;
+    return __privateMethod(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 __privateMethod(this, _applyGrantedPermissions, applyGrantedPermissions_fn).call(this, {
+      approvedPermissions,
+      subject,
+      mergePermissions: true,
+      preserveExistingPermissions: true,
+      requestData
+    });
   }
   /**
    * Validates the specified permission by:
@@ -952,9 +1019,11 @@ var PermissionController = class extends BaseController {
     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 {
       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 __privateMethod(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() } = options;
+    this.validateRequestedPermissions(origin, requestedPermissions);
+    const currentPermissions = this.getPermissions(origin) ?? {};
+    const [newPermissions, permissionDiffMap] = __privateMethod(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 InvalidMergedPermissionsError(
+          origin,
+          error,
+          permissionDiffMap
+        );
+      }
+      throw internalError("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 __privateMethod(this, _handleApprovedPermissions, handleApprovedPermissions_fn).call(this, {
+      subject,
+      metadata,
+      preserveExistingPermissions: false,
+      approvedRequest
+    });
   }
   /**
    * Validates requested permissions. Throws if validation fails.
@@ -1375,9 +1493,187 @@ var PermissionController = class extends BaseController {
     )({ method, params, context: { origin } });
   }
 };
+_expectGetCaveatMerger = new WeakSet();
+expectGetCaveatMerger_fn = function(caveatType) {
+  const { merger } = this.getCaveatSpecification(caveatType);
+  if (merger === void 0) {
+    throw new 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 InvalidSubjectIdentifierError(origin);
+  }
+  const permissions = preserveExistingPermissions ? {
+    ...this.getPermissions(origin)
+  } : {};
+  for (const [requestedTarget, approvedPermission] of Object.entries(
+    approvedPermissions
+  )) {
+    if (!this.targetExists(requestedTarget)) {
+      throw methodNotFound(requestedTarget);
+    }
+    if (approvedPermission.parentCapability !== void 0 && requestedTarget !== approvedPermission.parentCapability) {
+      throw new 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 = constructPermission(permissionOptions);
+      performCaveatValidation = false;
+    }
+    if (mergePermissions) {
+      permission = __privateMethod(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 = immerProduce(
+    existingPermissions,
+    (draftExistingPermissions) => {
+      const leftPermissions = draftExistingPermissions;
+      Object.entries(incrementalRequestedPermissions).forEach(
+        ([targetName, rightPermission]) => {
+          const leftPermission = leftPermissions[targetName];
+          const [newPermission, caveatsDiff] = __privateMethod(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 } = collectUniqueAndPairedCaveats(leftPermission, rightPermission);
+  const [mergedCaveats, caveatDiffMap] = caveatPairs.reduce(
+    ([caveats, diffMap], [leftCaveat, rightCaveat]) => {
+      const [newCaveat, diff] = __privateMethod(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] = __privateMethod(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 CaveatMergeTypeMismatchError(leftCaveat.type, rightCaveat.type);
+  }
+  const merger = __privateMethod(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
+  ];
+};
 
 export {
   CaveatMutatorOperation,
   PermissionController
 };
-//# sourceMappingURL=chunk-MCDOYEJY.mjs.map
+//# sourceMappingURL=chunk-4B6NOD2D.mjs.map