@metamask/permission-controller 12.2.1 → 12.3.0

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [12.3.0]
+
+### 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
+
+- Bump `@metamask/approval-controller` from `^9.0.0` to `^9.0.1` ([#8317](https://github.com/MetaMask/core/pull/8317))
+- Bump `@metamask/base-controller` from `^9.0.0` to `^9.0.1` ([#8317](https://github.com/MetaMask/core/pull/8317))
+- Bump `@metamask/json-rpc-engine` from `^10.2.3` to `^10.2.4` ([#8317](https://github.com/MetaMask/core/pull/8317))
+- Bump `@metamask/messenger` from `^0.3.0` to `^1.0.0` ([#8317](https://github.com/MetaMask/core/pull/8317))
+
+### Deprecated
+
+- 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
@@ -397,7 +447,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
     All changes listed after this point were applied to this package following the monorepo conversion.
 
-[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@12.2.1...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@12.3.0...HEAD
+[12.3.0]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@12.2.1...@metamask/permission-controller@12.3.0
 [12.2.1]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@12.2.0...@metamask/permission-controller@12.2.1
 [12.2.0]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@12.1.1...@metamask/permission-controller@12.2.0
 [12.1.1]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@12.1.0...@metamask/permission-controller@12.1.1

package/dist/PermissionController-method-action-types.cjs

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=PermissionController-method-action-types.cjs.map

package/dist/PermissionController-method-action-types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"PermissionController-method-action-types.cjs","sourceRoot":"","sources":["../src/PermissionController-method-action-types.ts"],"names":[],"mappings":";AAAA;;;GAGG","sourcesContent":["/**\n * This file is auto generated.\n * Do not edit manually.\n */\n\nimport type { PermissionController } from './PermissionController';\n\n/**\n * Clears the state of the controller.\n */\nexport type PermissionControllerClearStateAction = {\n  type: `PermissionController:clearState`;\n  handler: PermissionController['clearState'];\n};\n\n/**\n * Gets a list of all origins of subjects.\n *\n * @returns The origins (i.e. IDs) of all subjects.\n */\nexport type PermissionControllerGetSubjectNamesAction = {\n  type: `PermissionController:getSubjectNames`;\n  handler: PermissionController['getSubjectNames'];\n};\n\n/**\n * Gets all permissions for the specified subject, if any.\n *\n * @param origin - The origin of the subject.\n * @returns The permissions of the subject, if any.\n */\nexport type PermissionControllerGetPermissionsAction = {\n  type: `PermissionController:getPermissions`;\n  handler: PermissionController['getPermissions'];\n};\n\n/**\n * Checks whether the subject with the specified origin has the specified\n * permission.\n *\n * @param origin - The origin of the subject.\n * @param target - The target name of the permission.\n * @returns Whether the subject has the permission.\n */\nexport type PermissionControllerHasPermissionAction = {\n  type: `PermissionController:hasPermission`;\n  handler: PermissionController['hasPermission'];\n};\n\n/**\n * Checks whether the subject with the specified origin has any permissions.\n * Use this if you want to know if a subject \"exists\".\n *\n * @param origin - The origin of the subject to check.\n * @returns Whether the subject has any permissions.\n */\nexport type PermissionControllerHasPermissionsAction = {\n  type: `PermissionController:hasPermissions`;\n  handler: PermissionController['hasPermissions'];\n};\n\n/**\n * Revokes all permissions from the specified origin.\n *\n * Throws an error of the origin has no permissions.\n *\n * @param origin - The origin whose permissions to revoke.\n */\nexport type PermissionControllerRevokeAllPermissionsAction = {\n  type: `PermissionController:revokeAllPermissions`;\n  handler: PermissionController['revokeAllPermissions'];\n};\n\n/**\n * Revokes the specified permissions from the specified subjects.\n *\n * Throws an error if any of the subjects or permissions do not exist.\n *\n * @param subjectsAndPermissions - An object mapping subject origins\n * to arrays of permission target names to revoke.\n */\nexport type PermissionControllerRevokePermissionsAction = {\n  type: `PermissionController:revokePermissions`;\n  handler: PermissionController['revokePermissions'];\n};\n\n/**\n * Revokes all permissions corresponding to the specified target for all subjects.\n * Does nothing if no subjects or no such permission exists.\n *\n * @param target - The name of the target to revoke all permissions for.\n */\nexport type PermissionControllerRevokePermissionForAllSubjectsAction = {\n  type: `PermissionController:revokePermissionForAllSubjects`;\n  handler: PermissionController['revokePermissionForAllSubjects'];\n};\n\n/**\n * Gets the caveat of the specified type, if any, for the permission of\n * the subject corresponding to the given origin.\n *\n * Throws an error if the subject does not have a permission with the\n * specified target name.\n *\n * @template TargetName - The permission target name. Should be inferred.\n * @template CaveatType - The valid caveat types for the permission. Should\n * be inferred.\n * @param origin - The origin of the subject.\n * @param target - The target name of the permission.\n * @param caveatType - The type of the caveat to get.\n * @returns The caveat, or `undefined` if no such caveat exists.\n */\nexport type PermissionControllerGetCaveatAction = {\n  type: `PermissionController:getCaveat`;\n  handler: PermissionController['getCaveat'];\n};\n\n/**\n * Updates the value of the caveat of the specified type belonging to the\n * permission corresponding to the given subject origin and permission\n * target.\n *\n * For adding new caveats, use\n * {@link PermissionController.addCaveat}.\n *\n * Throws an error if no such permission or caveat exists.\n *\n * @template TargetName - The permission target name. Should be inferred.\n * @template CaveatType - The valid caveat types for the permission. Should\n * be inferred.\n * @param origin - The origin of the subject.\n * @param target - The target name of the permission.\n * @param caveatType - The type of the caveat to update.\n * @param caveatValue - The new value of the caveat.\n */\nexport type PermissionControllerUpdateCaveatAction = {\n  type: `PermissionController:updateCaveat`;\n  handler: PermissionController['updateCaveat'];\n};\n\n/**\n * Grants _approved_ permissions to the specified subject. Every permission and\n * caveat is stringently validated—including by calling their specification\n * validators—and an error is thrown if validation fails.\n *\n * ATTN: This method does **not** prompt the user for approval. User consent must\n * first be obtained through some other means.\n *\n * @see {@link PermissionController.requestPermissions} For initiating a\n * permissions request requiring user approval.\n * @param options - Options bag.\n * @param options.approvedPermissions - The requested permissions approved by\n * the user.\n * @param options.requestData - Permission request data. Passed to permission\n * factory functions.\n * @param options.preserveExistingPermissions - Whether to preserve the\n * subject's existing permissions.\n * @param options.subject - The subject to grant permissions to.\n * @returns The subject's new permission state. It may or may not have changed.\n */\nexport type PermissionControllerGrantPermissionsAction = {\n  type: `PermissionController:grantPermissions`;\n  handler: PermissionController['grantPermissions'];\n};\n\n/**\n * Incrementally grants _approved_ permissions to the specified subject. Every\n * permission and caveat is stringently validated—including by calling their\n * specification validators—and an error is thrown if validation fails.\n *\n * ATTN: This method does **not** prompt the user for approval. User consent must\n * first be obtained through some other means.\n *\n * @see {@link PermissionController.requestPermissionsIncremental} For initiating\n * an incremental permissions request requiring user approval.\n * @param options - Options bag.\n * @param options.approvedPermissions - The requested permissions approved by\n * the user.\n * @param options.requestData - Permission request data. Passed to permission\n * factory functions.\n * @param options.subject - The subject to grant permissions to.\n * @returns The subject's new permission state. It may or may not have changed.\n */\nexport type PermissionControllerGrantPermissionsIncrementalAction = {\n  type: `PermissionController:grantPermissionsIncremental`;\n  handler: PermissionController['grantPermissionsIncremental'];\n};\n\n/**\n * Initiates a permission request that requires user approval.\n *\n * Either this or {@link PermissionController.requestPermissionsIncremental}\n * should always be used to grant additional permissions to a subject,\n * unless user approval has been obtained through some other means.\n *\n * Permissions are validated at every step of the approval process, and this\n * method will reject if validation fails.\n *\n * @see {@link ApprovalController} For the user approval logic.\n * @see {@link PermissionController.acceptPermissionsRequest} For the method\n * that _accepts_ the request and resolves the user approval promise.\n * @see {@link PermissionController.rejectPermissionsRequest} For the method\n * that _rejects_ the request and the user approval promise.\n * @param subject - The grantee subject.\n * @param requestedPermissions - The requested permissions.\n * @param options - Additional options.\n * @param options.id - The id of the permissions request. Defaults to a unique\n * id.\n * @param options.preserveExistingPermissions - Whether to preserve the\n * subject's existing permissions. Defaults to `true`.\n * @param options.metadata - Additional metadata about the permission request.\n * @returns The granted permissions and request metadata.\n */\nexport type PermissionControllerRequestPermissionsAction = {\n  type: `PermissionController:requestPermissions`;\n  handler: PermissionController['requestPermissions'];\n};\n\n/**\n * Initiates an incremental permission request that prompts for user approval.\n * Incremental permission requests allow the caller to replace existing and/or\n * add brand new permissions and caveats for the specified subject.\n *\n * Incremental permission request are merged with the subject's existing permissions\n * through a right-biased union, where the incremental permission are the right-hand\n * side of the merger. If both sides of the merger specify the same caveats for a\n * given permission, the caveats are merged using their specification's caveat value\n * merger property.\n *\n * Either this or {@link PermissionController.requestPermissions} should\n * always be used to grant additional permissions to a subject, unless user\n * approval has been obtained through some other means.\n *\n * Permissions are validated at every step of the approval process, and this\n * method will reject if validation fails.\n *\n * @see {@link ApprovalController} For the user approval logic.\n * @see {@link PermissionController.acceptPermissionsRequest} For the method\n * that _accepts_ the request and resolves the user approval promise.\n * @see {@link PermissionController.rejectPermissionsRequest} For the method\n * that _rejects_ the request and the user approval promise.\n * @param subject - The grantee subject.\n * @param requestedPermissions - The requested permissions.\n * @param options - Additional options.\n * @param options.id - The id of the permissions request. Defaults to a unique\n * id.\n * @param options.metadata - Additional metadata about the permission request.\n * @returns The granted permissions and request metadata.\n */\nexport type PermissionControllerRequestPermissionsIncrementalAction = {\n  type: `PermissionController:requestPermissionsIncremental`;\n  handler: PermissionController['requestPermissionsIncremental'];\n};\n\n/**\n * Gets the subject's endowments per the specified endowment permission.\n * Throws if the subject does not have the required permission or if the\n * permission is not an endowment permission.\n *\n * @param origin - The origin of the subject whose endowments to retrieve.\n * @param targetName - The name of the endowment permission. This must be a\n * valid permission target name.\n * @param requestData - Additional data associated with the request, if any.\n * Forwarded to the endowment getter function for the permission.\n * @returns The endowments, if any.\n */\nexport type PermissionControllerGetEndowmentsAction = {\n  type: `PermissionController:getEndowments`;\n  handler: PermissionController['getEndowments'];\n};\n\n/**\n * Union of all PermissionController action types.\n */\nexport type PermissionControllerMethodActions =\n  | PermissionControllerClearStateAction\n  | PermissionControllerGetSubjectNamesAction\n  | PermissionControllerGetPermissionsAction\n  | PermissionControllerHasPermissionAction\n  | PermissionControllerHasPermissionsAction\n  | PermissionControllerRevokeAllPermissionsAction\n  | PermissionControllerRevokePermissionsAction\n  | PermissionControllerRevokePermissionForAllSubjectsAction\n  | PermissionControllerGetCaveatAction\n  | PermissionControllerUpdateCaveatAction\n  | PermissionControllerGrantPermissionsAction\n  | PermissionControllerGrantPermissionsIncrementalAction\n  | PermissionControllerRequestPermissionsAction\n  | PermissionControllerRequestPermissionsIncrementalAction\n  | PermissionControllerGetEndowmentsAction;\n"]}

package/dist/PermissionController-method-action-types.d.cts

@@ -0,0 +1,259 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+import type { PermissionController } from "./PermissionController.cjs";
+/**
+ * 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;
+//# sourceMappingURL=PermissionController-method-action-types.d.cts.map

package/dist/PermissionController-method-action-types.d.cts.map

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

package/dist/PermissionController-method-action-types.d.mts

@@ -0,0 +1,259 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+import type { PermissionController } from "./PermissionController.mjs";
+/**
+ * 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;
+//# sourceMappingURL=PermissionController-method-action-types.d.mts.map

package/dist/PermissionController-method-action-types.d.mts.map

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

package/dist/PermissionController-method-action-types.mjs

@@ -0,0 +1,6 @@
+/**
+ * This file is auto generated.
+ * Do not edit manually.
+ */
+export {};
+//# sourceMappingURL=PermissionController-method-action-types.mjs.map