chore: Update Core Platform / Wallet Integrations controllers to expose all methods through messenger

packages/permission-controller/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Expose missing public `PermissionController` methods through its messenger ([#8201](https://github.com/MetaMask/core/pull/8201))
+  - The following actions are now available:
+    - `PermissionController:clearState`
+  - Corresponding action types (e.g. `PermissionControllerClearStateAction`) are
+    available as well.
+- Expose missing public `SubjectMetadataController` methods through its messenger ([#8201](https://github.com/MetaMask/core/pull/8201))
+  - The following actions are now available:
+    - `SubjectMetadataController:clearState`
+    - `SubjectMetadataController:trimMetadataState`
+  - Corresponding action types
+    (e.g. `SubjectMetadataControllerClearStateAction`) are available as well.
+
+### Changed
+
+- Deprecate action types in favor of `PermissionController...Action` and `SubjectMetadataController...Action` types ([#8201](https://github.com/MetaMask/core/pull/8201))
+  - For the `PermissionController`:
+    - `GetPermissionControllerState` is now `PermissionControllerGetStateAction`.
+    - `GetSubjects` is now `PermissionControllerGetSubjectsAction`.
+    - `GetPermissions` is now `PermissionControllerGetPermissionsAction`.
+    - `HasPermissions` is now `PermissionControllerHasPermissionsAction`.
+    - `HasPermission` is now `PermissionControllerHasPermissionAction`.
+    - `GrantPermissions` is now `PermissionControllerGrantPermissionsAction`.
+    - `GrantPermissionsIncremental` is now `PermissionControllerGrantPermissionsIncrementalAction`.
+    - `RequestPermissions` is now `PermissionControllerRequestPermissionsAction`.
+    - `RequestPermissionsIncremental` is now `PermissionControllerRequestPermissionsIncrementalAction`.
+    - `RevokePermissions` is now `PermissionControllerRevokePermissionsAction`.
+    - `RevokeAllPermissions` is now `PermissionControllerRevokeAllPermissionsAction`.
+    - `RevokePermissionForAllSubjects` is now `PermissionControllerRevokePermissionForAllSubjectsAction`.
+    - `UpdateCaveat` is now `PermissionControllerUpdateCaveatAction`.
+    - `GetCaveat` is now `PermissionControllerGetCaveatAction`.
+    - `ClearPermissions` is now `PermissionControllerClearPermissionsAction`.
+    - `GetEndowments` is now `PermissionControllerGetEndowmentsAction`.
+  - For the `SubjectMetadataController`:
+    - `GetSubjectMetadataControllerState` is now `SubjectMetadataControllerGetStateAction`.
+    - `GetSubjectMetadata` is now `SubjectMetadataControllerGetMetadataAction`.
+    - `AddSubjectMetadata` is now `SubjectMetadataControllerAddMetadataAction`.
+  - The old types are still exported but are now marked as deprecated and will
+    be removed in a future release.
+
 ## [12.2.1]
 
 ### Changed

packages/permission-controller/package.json

@@ -40,6 +40,7 @@
     "build:docs": "typedoc",
     "changelog:update": "../../scripts/update-changelog.sh @metamask/permission-controller",
     "changelog:validate": "../../scripts/validate-changelog.sh @metamask/permission-controller",
+    "generate-method-action-types": "tsx ../../scripts/generate-method-action-types.ts",
     "since-latest-release": "../../scripts/since-latest-release.sh",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest --reporters=jest-silent-reporter",
     "test:clean": "NODE_OPTIONS=--experimental-vm-modules jest --clearCache",
@@ -66,6 +67,7 @@
     "deepmerge": "^4.2.2",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.5",
+    "tsx": "^4.20.5",
     "typedoc": "^0.25.13",
     "typedoc-plugin-missing-exports": "^2.0.0",
     "typescript": "~5.3.3"

packages/permission-controller/src/PermissionController-method-action-types.ts

@@ -0,0 +1,290 @@
+/**
+ * This file is auto generated by `scripts/generate-method-action-types.ts`.
+ * Do not edit manually.
+ */
+
+import type { PermissionController } from './PermissionController';
+
+/**
+ * Clears the state of the controller.
+ */
+export type PermissionControllerClearStateAction = {
+  type: `PermissionController:clearState`;
+  handler: PermissionController['clearState'];
+};
+
+/**
+ * Gets a list of all origins of subjects.
+ *
+ * @returns The origins (i.e. IDs) of all subjects.
+ */
+export type PermissionControllerGetSubjectNamesAction = {
+  type: `PermissionController:getSubjectNames`;
+  handler: PermissionController['getSubjectNames'];
+};
+
+/**
+ * Gets all permissions for the specified subject, if any.
+ *
+ * @param origin - The origin of the subject.
+ * @returns The permissions of the subject, if any.
+ */
+export type PermissionControllerGetPermissionsAction = {
+  type: `PermissionController:getPermissions`;
+  handler: PermissionController['getPermissions'];
+};
+
+/**
+ * Checks whether the subject with the specified origin has the specified
+ * permission.
+ *
+ * @param origin - The origin of the subject.
+ * @param target - The target name of the permission.
+ * @returns Whether the subject has the permission.
+ */
+export type PermissionControllerHasPermissionAction = {
+  type: `PermissionController:hasPermission`;
+  handler: PermissionController['hasPermission'];
+};
+
+/**
+ * Checks whether the subject with the specified origin has any permissions.
+ * Use this if you want to know if a subject "exists".
+ *
+ * @param origin - The origin of the subject to check.
+ * @returns Whether the subject has any permissions.
+ */
+export type PermissionControllerHasPermissionsAction = {
+  type: `PermissionController:hasPermissions`;
+  handler: PermissionController['hasPermissions'];
+};
+
+/**
+ * Revokes all permissions from the specified origin.
+ *
+ * Throws an error of the origin has no permissions.
+ *
+ * @param origin - The origin whose permissions to revoke.
+ */
+export type PermissionControllerRevokeAllPermissionsAction = {
+  type: `PermissionController:revokeAllPermissions`;
+  handler: PermissionController['revokeAllPermissions'];
+};
+
+/**
+ * Revokes the specified permissions from the specified subjects.
+ *
+ * Throws an error if any of the subjects or permissions do not exist.
+ *
+ * @param subjectsAndPermissions - An object mapping subject origins
+ * to arrays of permission target names to revoke.
+ */
+export type PermissionControllerRevokePermissionsAction = {
+  type: `PermissionController:revokePermissions`;
+  handler: PermissionController['revokePermissions'];
+};
+
+/**
+ * Revokes all permissions corresponding to the specified target for all subjects.
+ * Does nothing if no subjects or no such permission exists.
+ *
+ * @param target - The name of the target to revoke all permissions for.
+ */
+export type PermissionControllerRevokePermissionForAllSubjectsAction = {
+  type: `PermissionController:revokePermissionForAllSubjects`;
+  handler: PermissionController['revokePermissionForAllSubjects'];
+};
+
+/**
+ * Gets the caveat of the specified type, if any, for the permission of
+ * the subject corresponding to the given origin.
+ *
+ * Throws an error if the subject does not have a permission with the
+ * specified target name.
+ *
+ * @template TargetName - The permission target name. Should be inferred.
+ * @template CaveatType - The valid caveat types for the permission. Should
+ * be inferred.
+ * @param origin - The origin of the subject.
+ * @param target - The target name of the permission.
+ * @param caveatType - The type of the caveat to get.
+ * @returns The caveat, or `undefined` if no such caveat exists.
+ */
+export type PermissionControllerGetCaveatAction = {
+  type: `PermissionController:getCaveat`;
+  handler: PermissionController['getCaveat'];
+};
+
+/**
+ * Updates the value of the caveat of the specified type belonging to the
+ * permission corresponding to the given subject origin and permission
+ * target.
+ *
+ * For adding new caveats, use
+ * {@link PermissionController.addCaveat}.
+ *
+ * Throws an error if no such permission or caveat exists.
+ *
+ * @template TargetName - The permission target name. Should be inferred.
+ * @template CaveatType - The valid caveat types for the permission. Should
+ * be inferred.
+ * @param origin - The origin of the subject.
+ * @param target - The target name of the permission.
+ * @param caveatType - The type of the caveat to update.
+ * @param caveatValue - The new value of the caveat.
+ */
+export type PermissionControllerUpdateCaveatAction = {
+  type: `PermissionController:updateCaveat`;
+  handler: PermissionController['updateCaveat'];
+};
+
+/**
+ * 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.requestPermissions} For initiating a
+ * 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.preserveExistingPermissions - Whether to preserve the
+ * subject's existing permissions.
+ * @param options.subject - The subject to grant permissions to.
+ * @returns The subject's new permission state. It may or may not have changed.
+ */
+export type PermissionControllerGrantPermissionsAction = {
+  type: `PermissionController:grantPermissions`;
+  handler: PermissionController['grantPermissions'];
+};
+
+/**
+ * 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.
+ */
+export type PermissionControllerGrantPermissionsIncrementalAction = {
+  type: `PermissionController:grantPermissionsIncremental`;
+  handler: PermissionController['grantPermissionsIncremental'];
+};
+
+/**
+ * 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.
+ *
+ * @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.preserveExistingPermissions - Whether to preserve the
+ * subject's existing permissions. Defaults to `true`.
+ * @param options.metadata - Additional metadata about the permission request.
+ * @returns The granted permissions and request metadata.
+ */
+export type PermissionControllerRequestPermissionsAction = {
+  type: `PermissionController:requestPermissions`;
+  handler: PermissionController['requestPermissions'];
+};
+
+/**
+ * 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.
+ */
+export type PermissionControllerRequestPermissionsIncrementalAction = {
+  type: `PermissionController:requestPermissionsIncremental`;
+  handler: PermissionController['requestPermissionsIncremental'];
+};
+
+/**
+ * Gets the subject's endowments per the specified endowment permission.
+ * Throws if the subject does not have the required permission or if the
+ * permission is not an endowment permission.
+ *
+ * @param origin - The origin of the subject whose endowments to retrieve.
+ * @param targetName - The name of the endowment permission. This must be a
+ * valid permission target name.
+ * @param requestData - Additional data associated with the request, if any.
+ * Forwarded to the endowment getter function for the permission.
+ * @returns The endowments, if any.
+ */
+export type PermissionControllerGetEndowmentsAction = {
+  type: `PermissionController:getEndowments`;
+  handler: PermissionController['getEndowments'];
+};
+
+/**
+ * Union of all PermissionController action types.
+ */
+export type PermissionControllerMethodActions =
+  | PermissionControllerClearStateAction
+  | PermissionControllerGetSubjectNamesAction
+  | PermissionControllerGetPermissionsAction
+  | PermissionControllerHasPermissionAction
+  | PermissionControllerHasPermissionsAction
+  | PermissionControllerRevokeAllPermissionsAction
+  | PermissionControllerRevokePermissionsAction
+  | PermissionControllerRevokePermissionForAllSubjectsAction
+  | PermissionControllerGetCaveatAction
+  | PermissionControllerUpdateCaveatAction
+  | PermissionControllerGrantPermissionsAction
+  | PermissionControllerGrantPermissionsIncrementalAction
+  | PermissionControllerRequestPermissionsAction
+  | PermissionControllerRequestPermissionsIncrementalAction
+  | PermissionControllerGetEndowmentsAction;