@metamask/permission-controller 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0]
+### Added
+- Allow restricting permissions by subject type ([#1233](https://github.com/MetaMask/core/pull/1233))
+
+### Changed
+- Move `SubjectMetadataController` to permission-controller package ([#1234](https://github.com/MetaMask/core/pull/1234))
+- Update minimum `eth-rpc-errors` version from `4.0.0` to `4.0.2` ([#1215](https://github.com/MetaMask/core/pull/1215))
+
+## [3.1.0]
+### Added
+- Add side-effects to permissions ([#1069](https://github.com/MetaMask/core/pull/1069))
+
 ## [3.0.0]
 ### Removed
 - **BREAKING:** Remove `isomorphic-fetch` ([#1106](https://github.com/MetaMask/controllers/pull/1106))
@@ -18,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - **BREAKING:** Update `@metamask/network-controller` peer dependency to v3 ([#1041](https://github.com/MetaMask/controllers/pull/1041))
 - Rename this repository to `core` ([#1031](https://github.com/MetaMask/controllers/pull/1031))
-- Update `@metamask/controller-utils` package ([#1041](https://github.com/MetaMask/controllers/pull/1041)) 
+- Update `@metamask/controller-utils` package ([#1041](https://github.com/MetaMask/controllers/pull/1041))
 
 ## [1.0.2]
 ### Fixed
@@ -36,7 +48,9 @@ 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@3.0.0...HEAD
+[Unreleased]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@3.2.0...HEAD
+[3.2.0]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@3.1.0...@metamask/permission-controller@3.2.0
+[3.1.0]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@3.0.0...@metamask/permission-controller@3.1.0
 [3.0.0]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@2.0.0...@metamask/permission-controller@3.0.0
 [2.0.0]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@1.0.2...@metamask/permission-controller@2.0.0
 [1.0.2]: https://github.com/MetaMask/core/compare/@metamask/permission-controller@1.0.1...@metamask/permission-controller@1.0.2

package/dist/Caveat.d.ts

@@ -180,3 +180,4 @@ export declare function isRestrictedMethodCaveatSpecification(specification: Cav
 export declare function decorateWithCaveats<CaveatSpecifications extends CaveatSpecificationConstraint>(methodImplementation: RestrictedMethod<RestrictedMethodParameters, Json>, permission: Readonly<PermissionConstraint>, // bound to the requesting origin
 caveatSpecifications: CaveatSpecificationMap<CaveatSpecifications>): RestrictedMethod<RestrictedMethodParameters, Json>;
 export {};
+//# sourceMappingURL=Caveat.d.ts.map

package/dist/Caveat.d.ts.map

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

package/dist/Permission.d.ts

@@ -1,6 +1,9 @@
 import { Json } from '@metamask/types';
 import { NonEmptyArray } from '@metamask/controller-utils';
+import { ActionConstraint, EventConstraint } from '@metamask/base-controller';
+import type { SubjectType } from './SubjectMetadataController';
 import { CaveatConstraint } from './Caveat';
+import type { PermissionsRequest, SideEffectMessenger } from './PermissionController';
 /**
  * The origin of a subject.
  * Effectively the GUID of an entity that can have permissions.
@@ -236,6 +239,30 @@ export declare type EndowmentGetterParams = {
 export declare type EndowmentGetter<Endowments extends Json> = (options: EndowmentGetterParams) => Endowments | Promise<Endowments>;
 export declare type PermissionFactory<TargetPermission extends PermissionConstraint, RequestData extends Record<string, unknown>> = (options: PermissionOptions<TargetPermission>, requestData?: RequestData) => TargetPermission;
 export declare type PermissionValidatorConstraint = (permission: PermissionConstraint, origin?: OriginString, target?: string) => void;
+/**
+ * The parameters passed to the side-effect function.
+ */
+export declare type SideEffectParams<Actions extends ActionConstraint, Events extends EventConstraint> = {
+    requestData: PermissionsRequest;
+    messagingSystem: SideEffectMessenger<Actions, Events>;
+};
+/**
+ * A function that will execute actions as a permission side-effect.
+ */
+export declare type SideEffectHandler<Actions extends ActionConstraint, Events extends EventConstraint> = (params: SideEffectParams<Actions, Events>) => Promise<unknown>;
+/**
+ * The permissions side effects.
+ */
+export declare type PermissionSideEffect<Actions extends ActionConstraint, Events extends EventConstraint> = {
+    /**
+     * A method triggered when the permission is accepted by the user
+     */
+    onPermitted: SideEffectHandler<Actions, Events>;
+    /**
+     * A method triggered if a `onPermitted` method rejected.
+     */
+    onFailure?: SideEffectHandler<Actions, Events>;
+};
 /**
  * A utility type for ensuring that the given permission target key conforms to
  * our naming conventions.
@@ -306,6 +333,20 @@ declare type PermissionSpecificationBase<Type extends PermissionType> = {
      * The validator should throw an appropriate JSON-RPC error if validation fails.
      */
     validator?: PermissionValidatorConstraint;
+    /**
+     * The side-effect triggered by the {@link PermissionController} once the user approved it.
+     * The side-effect can only be an action allowed to be called inside the {@link PermissionController}.
+     *
+     * If the side-effect action fails, the permission that triggered it is revoked.
+     */
+    sideEffect?: PermissionSideEffect<any, any>;
+    /**
+     * The Permission may be available to only a subset of the subject types. If so, specify the subject types as an array.
+     * If a subject with a type not in this array tries to request the permission, the call will fail.
+     *
+     * Leaving this as undefined uses default behaviour where the permission is available to request for all subject types.
+     */
+    subjectTypes?: readonly SubjectType[];
 };
 /**
  * The constraint for restricted method permission specification objects.
@@ -420,3 +461,4 @@ export declare type ExtractPermissionSpecification<Specification extends Permiss
     targetKey: TargetKey;
 } ? Specification : never;
 export {};
+//# sourceMappingURL=Permission.d.ts.map

package/dist/Permission.d.ts.map

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

package/dist/Permission.js.map

@@ -1 +1 @@
-{"version":3,"file":"Permission.js","sourceRoot":"","sources":["../src/Permission.ts"],"names":[],"mappings":";;;AACA,mCAAgC;AAmMhC;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAEjC,OAA4C;IAC5C,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEpD,OAAO;QACL,EAAE,EAAE,IAAA,eAAM,GAAE;QACZ,gBAAgB,EAAE,MAAM;QACxB,OAAO;QACP,OAAO;QACP,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE;KACP,CAAC;AACxB,CAAC;AAZD,kDAYC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CACxB,UAAgC,EAChC,UAAkB;;IAElB,OAAO,MAAA,UAAU,CAAC,OAAO,0CAAE,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AAC1E,CAAC;AALD,gCAKC;AAwID;;GAEG;AACH,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,uDAAqC,CAAA;IAErC;;;OAGG;IACH,yCAAuB,CAAA;AACzB,CAAC,EAZW,cAAc,GAAd,sBAAc,KAAd,sBAAc,QAYzB;AA+KD;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAIlC,aAA4B,EAC5B,YAAkB;IAIlB,OAAO,aAAa,CAAC,cAAc,KAAK,YAAY,CAAC;AACvD,CAAC;AAVD,oDAUC","sourcesContent":["import { Json } from '@metamask/types';\nimport { nanoid } from 'nanoid';\nimport { NonEmptyArray } from '@metamask/controller-utils';\nimport { CaveatConstraint } from './Caveat';\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { PermissionController } from './PermissionController';\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { Caveat } from './Caveat';\n\n/**\n * The origin of a subject.\n * Effectively the GUID of an entity that can have permissions.\n */\nexport type OriginString = string;\n\n/**\n * The name of a permission target.\n */\ntype TargetName = string;\n\n/**\n * A `ZCAP-LD`-like permission object. A permission is associated with a\n * particular `invoker`, which is the holder of the permission. Possessing the\n * permission grants access to a particular restricted resource, identified by\n * the `parentCapability`. The use of the restricted resource may be further\n * restricted by any `caveats` associated with the permission.\n *\n * See the README for details.\n */\nexport type PermissionConstraint = {\n  /**\n   * The context(s) in which this capability is meaningful.\n   *\n   * It is required by the standard, but we make it optional since there is only\n   * one context in our usage (i.e. the user's MetaMask instance).\n   */\n  readonly '@context'?: NonEmptyArray<string>;\n\n  // TODO:TS4.4 Make optional\n  /**\n   * The caveats of the permission.\n   *\n   * @see {@link Caveat} For more information.\n   */\n  readonly caveats: null | NonEmptyArray<CaveatConstraint>;\n\n  /**\n   * The creation date of the permission, in UNIX epoch time.\n   */\n  readonly date: number;\n\n  /**\n   * The GUID of the permission object.\n   */\n  readonly id: string;\n\n  /**\n   * The origin string of the subject that has the permission.\n   */\n  readonly invoker: OriginString;\n\n  /**\n   * A pointer to the resource that possession of the capability grants\n   * access to, for example a JSON-RPC method or endowment.\n   */\n  readonly parentCapability: string;\n};\n\n/**\n * A `ZCAP-LD`-like permission object. A permission is associated with a\n * particular `invoker`, which is the holder of the permission. Possessing the\n * permission grants access to a particular restricted resource, identified by\n * the `parentCapability`. The use of the restricted resource may be further\n * restricted by any `caveats` associated with the permission.\n *\n * See the README for details.\n *\n * @template TargetKey - They key of the permission target that the permission\n * corresponds to.\n * @template AllowedCaveat - A union of the allowed {@link Caveat} types\n * for the permission.\n */\nexport type ValidPermission<\n  TargetKey extends TargetName,\n  AllowedCaveat extends CaveatConstraint,\n> = PermissionConstraint & {\n  // TODO:TS4.4 Make optional\n  /**\n   * The caveats of the permission.\n   *\n   * @see {@link Caveat} For more information.\n   */\n  readonly caveats: AllowedCaveat extends never\n    ? null\n    : NonEmptyArray<AllowedCaveat> | null;\n\n  /**\n   * A pointer to the resource that possession of the capability grants\n   * access to, for example a JSON-RPC method or endowment.\n   */\n  readonly parentCapability: ExtractPermissionTargetNames<TargetKey>;\n};\n\n/**\n * A utility type for ensuring that the given permission target name conforms to\n * our naming conventions.\n *\n * See the README for the distinction between target names and keys.\n */\ntype ValidTargetName<Name extends string> = Name extends `${string}*`\n  ? never\n  : Name extends `${string}_`\n  ? never\n  : Name;\n\n/**\n * A utility type for extracting permission target names from a union of target\n * keys.\n *\n * See the README for the distinction between target names and keys.\n *\n * @template Key - The target key type to extract target names from.\n */\nexport type ExtractPermissionTargetNames<Key extends string> = ValidTargetName<\n  Key extends `${infer Base}_*` ? `${Base}_${string}` : Key\n>;\n\n/**\n * Extracts the permission key of a particular name from a union of keys.\n * An internal utility type used in {@link ExtractPermissionTargetKey}.\n *\n * @template Key - The target key type to extract from.\n * @template Name - The name whose key to extract.\n */\ntype KeyOfTargetName<\n  Key extends string,\n  Name extends string,\n> = Name extends ExtractPermissionTargetNames<Key> ? Key : never;\n\n/**\n * A utility type for finding the permission target key corresponding to a\n * target name. In a way, the inverse of {@link ExtractPermissionTargetNames}.\n *\n * See the README for the distinction between target names and keys.\n *\n * @template Key - The target key type to extract from.\n * @template Name - The name whose key to extract.\n */\nexport type ExtractPermissionTargetKey<\n  Key extends string,\n  Name extends string,\n> = Key extends Name ? Key : Extract<Key, KeyOfTargetName<Key, Name>>;\n\n/**\n * Internal utility for extracting the members types of an array. The type\n * evalutes to `never` if the specified type is the empty tuple or neither\n * an array nor a tuple.\n *\n * @template ArrayType - The array type whose members to extract.\n */\ntype ExtractArrayMembers<ArrayType> = ArrayType extends []\n  ? never\n  : ArrayType extends any[] | readonly any[]\n  ? ArrayType[number]\n  : never;\n\n/**\n * A utility type for extracting the allowed caveat types for a particular\n * permission from a permission specification type.\n *\n * @template PermissionSpecification - The permission specification type to\n * extract valid caveat types from.\n */\nexport type ExtractAllowedCaveatTypes<\n  PermissionSpecification extends PermissionSpecificationConstraint,\n> = ExtractArrayMembers<PermissionSpecification['allowedCaveats']>;\n\n/**\n * The options object of {@link constructPermission}.\n *\n * @template TargetPermission - The {@link Permission} that will be constructed.\n */\nexport type PermissionOptions<TargetPermission extends PermissionConstraint> = {\n  target: TargetPermission['parentCapability'];\n  /**\n   * The origin string of the subject that has the permission.\n   */\n  invoker: OriginString;\n\n  /**\n   * The caveats of the permission.\n   * See {@link Caveat}.\n   */\n  caveats?: NonEmptyArray<CaveatConstraint>;\n};\n\n/**\n * The default permission factory function. Naively constructs a permission from\n * the inputs. Sets a default, random `id` if none is provided.\n *\n * @see {@link Permission} For more details.\n * @template TargetPermission- - The {@link Permission} that will be constructed.\n * @param options - The options for the permission.\n * @returns The new permission object.\n */\nexport function constructPermission<\n  TargetPermission extends PermissionConstraint,\n>(options: PermissionOptions<TargetPermission>): TargetPermission {\n  const { caveats = null, invoker, target } = options;\n\n  return {\n    id: nanoid(),\n    parentCapability: target,\n    invoker,\n    caveats,\n    date: new Date().getTime(),\n  } as TargetPermission;\n}\n\n/**\n * Gets the caveat of the specified type belonging to the specified permission.\n *\n * @param permission - The permission whose caveat to retrieve.\n * @param caveatType - The type of the caveat to retrieve.\n * @returns The caveat, or undefined if no such caveat exists.\n */\nexport function findCaveat(\n  permission: PermissionConstraint,\n  caveatType: string,\n): CaveatConstraint | undefined {\n  return permission.caveats?.find((caveat) => caveat.type === caveatType);\n}\n\n/**\n * A requested permission object. Just an object with any of the properties\n * of a {@link PermissionConstraint} object.\n */\ntype RequestedPermission = Partial<PermissionConstraint>;\n\n/**\n * A record of target names and their {@link RequestedPermission} objects.\n */\nexport type RequestedPermissions = Record<TargetName, RequestedPermission>;\n\n/**\n * The restricted method context object. Essentially a way to pass internal\n * arguments to restricted methods and caveat functions, most importantly the\n * requesting origin.\n */\ntype RestrictedMethodContext = Readonly<{\n  origin: OriginString;\n  [key: string]: any;\n}>;\n\nexport type RestrictedMethodParameters = Json[] | Record<string, Json> | void;\n\n/**\n * The arguments passed to a restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n */\nexport type RestrictedMethodOptions<Params extends RestrictedMethodParameters> =\n  {\n    method: TargetName;\n    params?: Params;\n    context: RestrictedMethodContext;\n  };\n\n/**\n * A synchronous restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n * @template Result - The JSON-RPC result of the restricted method.\n */\nexport type SyncRestrictedMethod<\n  Params extends RestrictedMethodParameters,\n  Result extends Json,\n> = (args: RestrictedMethodOptions<Params>) => Result;\n\n/**\n * An asynchronous restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n * @template Result - The JSON-RPC result of the restricted method.\n */\nexport type AsyncRestrictedMethod<\n  Params extends RestrictedMethodParameters,\n  Result extends Json,\n> = (args: RestrictedMethodOptions<Params>) => Promise<Result>;\n\n/**\n * A synchronous or asynchronous restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n * @template Result - The JSON-RPC result of the restricted method.\n */\nexport type RestrictedMethod<\n  Params extends RestrictedMethodParameters,\n  Result extends Json,\n> =\n  | SyncRestrictedMethod<Params, Result>\n  | AsyncRestrictedMethod<Params, Result>;\n\nexport type ValidRestrictedMethod<\n  MethodImplementation extends RestrictedMethod<any, any>,\n> = MethodImplementation extends (args: infer Options) => Json | Promise<Json>\n  ? Options extends RestrictedMethodOptions<RestrictedMethodParameters>\n    ? MethodImplementation\n    : never\n  : never;\n\n/**\n * {@link EndowmentGetter} parameter object.\n */\nexport type EndowmentGetterParams = {\n  /**\n   * The origin of the requesting subject.\n   */\n  origin: string;\n\n  /**\n   * Any additional data associated with the request.\n   */\n  requestData?: unknown;\n\n  [key: string]: unknown;\n};\n\n/**\n * A synchronous or asynchronous function that gets the endowments for a\n * particular endowment permission. The getter receives the origin of the\n * requesting subject and, optionally, additional request metadata.\n */\nexport type EndowmentGetter<Endowments extends Json> = (\n  options: EndowmentGetterParams,\n) => Endowments | Promise<Endowments>;\n\nexport type PermissionFactory<\n  TargetPermission extends PermissionConstraint,\n  RequestData extends Record<string, unknown>,\n> = (\n  options: PermissionOptions<TargetPermission>,\n  requestData?: RequestData,\n) => TargetPermission;\n\nexport type PermissionValidatorConstraint = (\n  permission: PermissionConstraint,\n  origin?: OriginString,\n  target?: string,\n) => void;\n\n/**\n * A utility type for ensuring that the given permission target key conforms to\n * our naming conventions.\n *\n * See the README for the distinction between target names and keys.\n *\n * @template Key - The target key string to apply the constraint to.\n */\ntype ValidTargetKey<Key extends string> = Key extends `${string}_*`\n  ? Key\n  : Key extends `${string}_`\n  ? never\n  : Key extends `${string}*`\n  ? never\n  : Key;\n\n/**\n * The different possible types of permissions.\n */\nexport enum PermissionType {\n  /**\n   * A restricted JSON-RPC method. A subject must have the requisite permission\n   * to call a restricted JSON-RPC method.\n   */\n  RestrictedMethod = 'RestrictedMethod',\n\n  /**\n   * An \"endowment\" granted to subjects that possess the requisite permission,\n   * such as a global environment variable exposing a restricted API, etc.\n   */\n  Endowment = 'Endowment',\n}\n\n/**\n * The base constraint for permission specification objects. Every\n * {@link Permission} supported by a {@link PermissionController} must have an\n * associated specification, which is the source of truth for all permission-\n * related types. A permission specification includes the list of permitted\n * caveats, and any factory and validation functions specified by the consumer.\n * A concrete permission specification may specify further fields as necessary.\n *\n * See the README for more details.\n */\ntype PermissionSpecificationBase<Type extends PermissionType> = {\n  /**\n   * The type of the specified permission.\n   */\n  permissionType: Type;\n\n  /**\n   * The target resource of the permission. The shape of this string depends on\n   * the permission type. For example, a restricted method target key will\n   * consist of either a complete method name or the prefix of a namespaced\n   * method, e.g. `wallet_snap_*`.\n   */\n  targetKey: string;\n\n  /**\n   * An array of the caveat types that may be added to instances of this\n   * permission.\n   */\n  allowedCaveats: Readonly<NonEmptyArray<string>> | null;\n\n  /**\n   * The factory function used to get permission objects. Permissions returned\n   * by this function are presumed to valid, and they will not be passed to the\n   * validator function associated with this specification (if any). In other\n   * words, the factory function should validate the permissions it creates.\n   *\n   * If no factory is specified, the {@link Permission} constructor will be\n   * used, and the validator function (if specified) will be called on newly\n   * constructed permissions.\n   */\n  factory?: PermissionFactory<any, Record<string, unknown>>;\n\n  /**\n   * The validator function used to validate permissions of the associated type\n   * whenever they are mutated. The only way a permission can be legally mutated\n   * is when its caveats are modified by the permission controller.\n   *\n   * The validator should throw an appropriate JSON-RPC error if validation fails.\n   */\n  validator?: PermissionValidatorConstraint;\n};\n\n/**\n * The constraint for restricted method permission specification objects.\n * Permissions that correspond to JSON-RPC methods are specified using objects\n * that conform to this type.\n *\n * See the README for more details.\n */\nexport type RestrictedMethodSpecificationConstraint =\n  PermissionSpecificationBase<PermissionType.RestrictedMethod> & {\n    /**\n     * The implementation of the restricted method that the permission\n     * corresponds to.\n     */\n    methodImplementation: RestrictedMethod<any, any>;\n  };\n\n/**\n * The constraint for endowment permission specification objects. Permissions\n * that endow callers with some restricted resource are specified using objects\n * that conform to this type.\n *\n * See the README for more details.\n */\nexport type EndowmentSpecificationConstraint =\n  PermissionSpecificationBase<PermissionType.Endowment> & {\n    /**\n     * The {@link EndowmentGetter} function for the permission. This function\n     * will be called by the {@link PermissionController} whenever the\n     * permission is invoked, after which the host can apply the endowments to\n     * the requesting subject in the intended manner.\n     */\n    endowmentGetter: EndowmentGetter<any>;\n  };\n\n/**\n * The constraint for permission specification objects. Every {@link Permission}\n * supported by a {@link PermissionController} must have an associated\n * specification, which is the source of truth for all permission-related types.\n * All specifications must adhere to the {@link PermissionSpecificationBase}\n * interface, but specifications may have different fields depending on the\n * {@link PermissionType}.\n *\n * See the README for more details.\n */\nexport type PermissionSpecificationConstraint =\n  | EndowmentSpecificationConstraint\n  | RestrictedMethodSpecificationConstraint;\n\n/**\n * Options for {@link PermissionSpecificationBuilder} functions.\n */\ntype PermissionSpecificationBuilderOptions<\n  FactoryHooks extends Record<string, unknown>,\n  MethodHooks extends Record<string, unknown>,\n  ValidatorHooks extends Record<string, unknown>,\n> = {\n  targetKey?: string;\n  allowedCaveats?: Readonly<NonEmptyArray<string>> | null;\n  factoryHooks?: FactoryHooks;\n  methodHooks?: MethodHooks;\n  validatorHooks?: ValidatorHooks;\n};\n\n/**\n * A function that builds a permission specification. Modules that specify\n * permissions for external consumption should make this their primary /\n * default export so that host applications can use them to generate concrete\n * specifications tailored to their requirements.\n */\nexport type PermissionSpecificationBuilder<\n  Type extends PermissionType,\n  Options extends PermissionSpecificationBuilderOptions<any, any, any>,\n  Specification extends PermissionSpecificationConstraint & {\n    permissionType: Type;\n  },\n> = (options: Options) => Specification;\n\n/**\n * A restricted method permission export object, containing the\n * {@link PermissionSpecificationBuilder} function and \"hook name\" objects.\n */\nexport type PermissionSpecificationBuilderExportConstraint = {\n  targetKey: string;\n  specificationBuilder: PermissionSpecificationBuilder<\n    PermissionType,\n    PermissionSpecificationBuilderOptions<any, any, any>,\n    PermissionSpecificationConstraint\n  >;\n  factoryHookNames?: Record<string, true>;\n  methodHookNames?: Record<string, true>;\n  validatorHookNames?: Record<string, true>;\n};\n\ntype ValidRestrictedMethodSpecification<\n  Specification extends RestrictedMethodSpecificationConstraint,\n> = Specification['methodImplementation'] extends ValidRestrictedMethod<\n  Specification['methodImplementation']\n>\n  ? Specification\n  : never;\n\n/**\n * Constraint for {@link PermissionSpecificationConstraint} objects that\n * evaluates to `never` if the specification contains any invalid fields.\n *\n * @template Specification - The permission specification to validate.\n */\nexport type ValidPermissionSpecification<\n  Specification extends PermissionSpecificationConstraint,\n> = Specification['targetKey'] extends ValidTargetKey<\n  Specification['targetKey']\n>\n  ? Specification['permissionType'] extends PermissionType.Endowment\n    ? Specification\n    : Specification['permissionType'] extends PermissionType.RestrictedMethod\n    ? ValidRestrictedMethodSpecification<\n        Extract<Specification, RestrictedMethodSpecificationConstraint>\n      >\n    : never\n  : never;\n\n/**\n * Checks that the specification has the expected permission type.\n *\n * @param specification - The specification to check.\n * @param expectedType - The expected permission type.\n * @template Specification - The specification to check.\n * @template Type - The expected permission type.\n * @returns Whether or not the specification is of the expected type.\n */\nexport function hasSpecificationType<\n  Specification extends PermissionSpecificationConstraint,\n  Type extends PermissionType,\n>(\n  specification: Specification,\n  expectedType: Type,\n): specification is Specification & {\n  permissionType: Type;\n} {\n  return specification.permissionType === expectedType;\n}\n\n/**\n * The specifications for all permissions supported by a particular\n * {@link PermissionController}.\n *\n * @template Specifications - The union of all {@link PermissionSpecificationConstraint} types.\n */\nexport type PermissionSpecificationMap<\n  Specification extends PermissionSpecificationConstraint,\n> = {\n  [TargetKey in Specification['targetKey']]: Specification extends {\n    targetKey: TargetKey;\n  }\n    ? Specification\n    : never;\n};\n\n/**\n * Extracts a specific {@link PermissionSpecificationConstraint} from a union of\n * permission specifications.\n *\n * @template Specification - The specification union type to extract from.\n * @template TargetKey - The `targetKey` of the specification to extract.\n */\nexport type ExtractPermissionSpecification<\n  Specification extends PermissionSpecificationConstraint,\n  TargetKey extends Specification['targetKey'],\n> = Specification extends {\n  targetKey: TargetKey;\n}\n  ? Specification\n  : never;\n"]}
+{"version":3,"file":"Permission.js","sourceRoot":"","sources":["../src/Permission.ts"],"names":[],"mappings":";;;AACA,mCAAgC;AA0MhC;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAEjC,OAA4C;IAC5C,MAAM,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEpD,OAAO;QACL,EAAE,EAAE,IAAA,eAAM,GAAE;QACZ,gBAAgB,EAAE,MAAM;QACxB,OAAO;QACP,OAAO;QACP,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE;KACP,CAAC;AACxB,CAAC;AAZD,kDAYC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CACxB,UAAgC,EAChC,UAAkB;;IAElB,OAAO,MAAA,UAAU,CAAC,OAAO,0CAAE,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AAC1E,CAAC;AALD,gCAKC;AA4KD;;GAEG;AACH,IAAY,cAYX;AAZD,WAAY,cAAc;IACxB;;;OAGG;IACH,uDAAqC,CAAA;IAErC;;;OAGG;IACH,yCAAuB,CAAA;AACzB,CAAC,EAZW,cAAc,GAAd,sBAAc,KAAd,sBAAc,QAYzB;AA+LD;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAIlC,aAA4B,EAC5B,YAAkB;IAIlB,OAAO,aAAa,CAAC,cAAc,KAAK,YAAY,CAAC;AACvD,CAAC;AAVD,oDAUC","sourcesContent":["import { Json } from '@metamask/types';\nimport { nanoid } from 'nanoid';\nimport { NonEmptyArray } from '@metamask/controller-utils';\nimport { ActionConstraint, EventConstraint } from '@metamask/base-controller';\nimport type { SubjectType } from './SubjectMetadataController';\nimport { CaveatConstraint } from './Caveat';\n\nimport type {\n  // eslint-disable-next-line @typescript-eslint/no-unused-vars\n  PermissionController,\n  PermissionsRequest,\n  SideEffectMessenger,\n} from './PermissionController';\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { Caveat } from './Caveat';\n\n/**\n * The origin of a subject.\n * Effectively the GUID of an entity that can have permissions.\n */\nexport type OriginString = string;\n\n/**\n * The name of a permission target.\n */\ntype TargetName = string;\n\n/**\n * A `ZCAP-LD`-like permission object. A permission is associated with a\n * particular `invoker`, which is the holder of the permission. Possessing the\n * permission grants access to a particular restricted resource, identified by\n * the `parentCapability`. The use of the restricted resource may be further\n * restricted by any `caveats` associated with the permission.\n *\n * See the README for details.\n */\nexport type PermissionConstraint = {\n  /**\n   * The context(s) in which this capability is meaningful.\n   *\n   * It is required by the standard, but we make it optional since there is only\n   * one context in our usage (i.e. the user's MetaMask instance).\n   */\n  readonly '@context'?: NonEmptyArray<string>;\n\n  // TODO:TS4.4 Make optional\n  /**\n   * The caveats of the permission.\n   *\n   * @see {@link Caveat} For more information.\n   */\n  readonly caveats: null | NonEmptyArray<CaveatConstraint>;\n\n  /**\n   * The creation date of the permission, in UNIX epoch time.\n   */\n  readonly date: number;\n\n  /**\n   * The GUID of the permission object.\n   */\n  readonly id: string;\n\n  /**\n   * The origin string of the subject that has the permission.\n   */\n  readonly invoker: OriginString;\n\n  /**\n   * A pointer to the resource that possession of the capability grants\n   * access to, for example a JSON-RPC method or endowment.\n   */\n  readonly parentCapability: string;\n};\n\n/**\n * A `ZCAP-LD`-like permission object. A permission is associated with a\n * particular `invoker`, which is the holder of the permission. Possessing the\n * permission grants access to a particular restricted resource, identified by\n * the `parentCapability`. The use of the restricted resource may be further\n * restricted by any `caveats` associated with the permission.\n *\n * See the README for details.\n *\n * @template TargetKey - They key of the permission target that the permission\n * corresponds to.\n * @template AllowedCaveat - A union of the allowed {@link Caveat} types\n * for the permission.\n */\nexport type ValidPermission<\n  TargetKey extends TargetName,\n  AllowedCaveat extends CaveatConstraint,\n> = PermissionConstraint & {\n  // TODO:TS4.4 Make optional\n  /**\n   * The caveats of the permission.\n   *\n   * @see {@link Caveat} For more information.\n   */\n  readonly caveats: AllowedCaveat extends never\n    ? null\n    : NonEmptyArray<AllowedCaveat> | null;\n\n  /**\n   * A pointer to the resource that possession of the capability grants\n   * access to, for example a JSON-RPC method or endowment.\n   */\n  readonly parentCapability: ExtractPermissionTargetNames<TargetKey>;\n};\n\n/**\n * A utility type for ensuring that the given permission target name conforms to\n * our naming conventions.\n *\n * See the README for the distinction between target names and keys.\n */\ntype ValidTargetName<Name extends string> = Name extends `${string}*`\n  ? never\n  : Name extends `${string}_`\n  ? never\n  : Name;\n\n/**\n * A utility type for extracting permission target names from a union of target\n * keys.\n *\n * See the README for the distinction between target names and keys.\n *\n * @template Key - The target key type to extract target names from.\n */\nexport type ExtractPermissionTargetNames<Key extends string> = ValidTargetName<\n  Key extends `${infer Base}_*` ? `${Base}_${string}` : Key\n>;\n\n/**\n * Extracts the permission key of a particular name from a union of keys.\n * An internal utility type used in {@link ExtractPermissionTargetKey}.\n *\n * @template Key - The target key type to extract from.\n * @template Name - The name whose key to extract.\n */\ntype KeyOfTargetName<\n  Key extends string,\n  Name extends string,\n> = Name extends ExtractPermissionTargetNames<Key> ? Key : never;\n\n/**\n * A utility type for finding the permission target key corresponding to a\n * target name. In a way, the inverse of {@link ExtractPermissionTargetNames}.\n *\n * See the README for the distinction between target names and keys.\n *\n * @template Key - The target key type to extract from.\n * @template Name - The name whose key to extract.\n */\nexport type ExtractPermissionTargetKey<\n  Key extends string,\n  Name extends string,\n> = Key extends Name ? Key : Extract<Key, KeyOfTargetName<Key, Name>>;\n\n/**\n * Internal utility for extracting the members types of an array. The type\n * evalutes to `never` if the specified type is the empty tuple or neither\n * an array nor a tuple.\n *\n * @template ArrayType - The array type whose members to extract.\n */\ntype ExtractArrayMembers<ArrayType> = ArrayType extends []\n  ? never\n  : ArrayType extends any[] | readonly any[]\n  ? ArrayType[number]\n  : never;\n\n/**\n * A utility type for extracting the allowed caveat types for a particular\n * permission from a permission specification type.\n *\n * @template PermissionSpecification - The permission specification type to\n * extract valid caveat types from.\n */\nexport type ExtractAllowedCaveatTypes<\n  PermissionSpecification extends PermissionSpecificationConstraint,\n> = ExtractArrayMembers<PermissionSpecification['allowedCaveats']>;\n\n/**\n * The options object of {@link constructPermission}.\n *\n * @template TargetPermission - The {@link Permission} that will be constructed.\n */\nexport type PermissionOptions<TargetPermission extends PermissionConstraint> = {\n  target: TargetPermission['parentCapability'];\n  /**\n   * The origin string of the subject that has the permission.\n   */\n  invoker: OriginString;\n\n  /**\n   * The caveats of the permission.\n   * See {@link Caveat}.\n   */\n  caveats?: NonEmptyArray<CaveatConstraint>;\n};\n\n/**\n * The default permission factory function. Naively constructs a permission from\n * the inputs. Sets a default, random `id` if none is provided.\n *\n * @see {@link Permission} For more details.\n * @template TargetPermission- - The {@link Permission} that will be constructed.\n * @param options - The options for the permission.\n * @returns The new permission object.\n */\nexport function constructPermission<\n  TargetPermission extends PermissionConstraint,\n>(options: PermissionOptions<TargetPermission>): TargetPermission {\n  const { caveats = null, invoker, target } = options;\n\n  return {\n    id: nanoid(),\n    parentCapability: target,\n    invoker,\n    caveats,\n    date: new Date().getTime(),\n  } as TargetPermission;\n}\n\n/**\n * Gets the caveat of the specified type belonging to the specified permission.\n *\n * @param permission - The permission whose caveat to retrieve.\n * @param caveatType - The type of the caveat to retrieve.\n * @returns The caveat, or undefined if no such caveat exists.\n */\nexport function findCaveat(\n  permission: PermissionConstraint,\n  caveatType: string,\n): CaveatConstraint | undefined {\n  return permission.caveats?.find((caveat) => caveat.type === caveatType);\n}\n\n/**\n * A requested permission object. Just an object with any of the properties\n * of a {@link PermissionConstraint} object.\n */\ntype RequestedPermission = Partial<PermissionConstraint>;\n\n/**\n * A record of target names and their {@link RequestedPermission} objects.\n */\nexport type RequestedPermissions = Record<TargetName, RequestedPermission>;\n\n/**\n * The restricted method context object. Essentially a way to pass internal\n * arguments to restricted methods and caveat functions, most importantly the\n * requesting origin.\n */\ntype RestrictedMethodContext = Readonly<{\n  origin: OriginString;\n  [key: string]: any;\n}>;\n\nexport type RestrictedMethodParameters = Json[] | Record<string, Json> | void;\n\n/**\n * The arguments passed to a restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n */\nexport type RestrictedMethodOptions<Params extends RestrictedMethodParameters> =\n  {\n    method: TargetName;\n    params?: Params;\n    context: RestrictedMethodContext;\n  };\n\n/**\n * A synchronous restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n * @template Result - The JSON-RPC result of the restricted method.\n */\nexport type SyncRestrictedMethod<\n  Params extends RestrictedMethodParameters,\n  Result extends Json,\n> = (args: RestrictedMethodOptions<Params>) => Result;\n\n/**\n * An asynchronous restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n * @template Result - The JSON-RPC result of the restricted method.\n */\nexport type AsyncRestrictedMethod<\n  Params extends RestrictedMethodParameters,\n  Result extends Json,\n> = (args: RestrictedMethodOptions<Params>) => Promise<Result>;\n\n/**\n * A synchronous or asynchronous restricted method implementation.\n *\n * @template Params - The JSON-RPC parameters of the restricted method.\n * @template Result - The JSON-RPC result of the restricted method.\n */\nexport type RestrictedMethod<\n  Params extends RestrictedMethodParameters,\n  Result extends Json,\n> =\n  | SyncRestrictedMethod<Params, Result>\n  | AsyncRestrictedMethod<Params, Result>;\n\nexport type ValidRestrictedMethod<\n  MethodImplementation extends RestrictedMethod<any, any>,\n> = MethodImplementation extends (args: infer Options) => Json | Promise<Json>\n  ? Options extends RestrictedMethodOptions<RestrictedMethodParameters>\n    ? MethodImplementation\n    : never\n  : never;\n\n/**\n * {@link EndowmentGetter} parameter object.\n */\nexport type EndowmentGetterParams = {\n  /**\n   * The origin of the requesting subject.\n   */\n  origin: string;\n\n  /**\n   * Any additional data associated with the request.\n   */\n  requestData?: unknown;\n\n  [key: string]: unknown;\n};\n\n/**\n * A synchronous or asynchronous function that gets the endowments for a\n * particular endowment permission. The getter receives the origin of the\n * requesting subject and, optionally, additional request metadata.\n */\nexport type EndowmentGetter<Endowments extends Json> = (\n  options: EndowmentGetterParams,\n) => Endowments | Promise<Endowments>;\n\nexport type PermissionFactory<\n  TargetPermission extends PermissionConstraint,\n  RequestData extends Record<string, unknown>,\n> = (\n  options: PermissionOptions<TargetPermission>,\n  requestData?: RequestData,\n) => TargetPermission;\n\nexport type PermissionValidatorConstraint = (\n  permission: PermissionConstraint,\n  origin?: OriginString,\n  target?: string,\n) => void;\n\n/**\n * The parameters passed to the side-effect function.\n */\nexport type SideEffectParams<\n  Actions extends ActionConstraint,\n  Events extends EventConstraint,\n> = {\n  requestData: PermissionsRequest;\n  messagingSystem: SideEffectMessenger<Actions, Events>;\n};\n\n/**\n * A function that will execute actions as a permission side-effect.\n */\nexport type SideEffectHandler<\n  Actions extends ActionConstraint,\n  Events extends EventConstraint,\n> = (params: SideEffectParams<Actions, Events>) => Promise<unknown>;\n\n/**\n * The permissions side effects.\n */\nexport type PermissionSideEffect<\n  Actions extends ActionConstraint,\n  Events extends EventConstraint,\n> = {\n  /**\n   * A method triggered when the permission is accepted by the user\n   */\n  onPermitted: SideEffectHandler<Actions, Events>;\n  /**\n   * A method triggered if a `onPermitted` method rejected.\n   */\n  onFailure?: SideEffectHandler<Actions, Events>;\n};\n\n/**\n * A utility type for ensuring that the given permission target key conforms to\n * our naming conventions.\n *\n * See the README for the distinction between target names and keys.\n *\n * @template Key - The target key string to apply the constraint to.\n */\ntype ValidTargetKey<Key extends string> = Key extends `${string}_*`\n  ? Key\n  : Key extends `${string}_`\n  ? never\n  : Key extends `${string}*`\n  ? never\n  : Key;\n\n/**\n * The different possible types of permissions.\n */\nexport enum PermissionType {\n  /**\n   * A restricted JSON-RPC method. A subject must have the requisite permission\n   * to call a restricted JSON-RPC method.\n   */\n  RestrictedMethod = 'RestrictedMethod',\n\n  /**\n   * An \"endowment\" granted to subjects that possess the requisite permission,\n   * such as a global environment variable exposing a restricted API, etc.\n   */\n  Endowment = 'Endowment',\n}\n\n/**\n * The base constraint for permission specification objects. Every\n * {@link Permission} supported by a {@link PermissionController} must have an\n * associated specification, which is the source of truth for all permission-\n * related types. A permission specification includes the list of permitted\n * caveats, and any factory and validation functions specified by the consumer.\n * A concrete permission specification may specify further fields as necessary.\n *\n * See the README for more details.\n */\ntype PermissionSpecificationBase<Type extends PermissionType> = {\n  /**\n   * The type of the specified permission.\n   */\n  permissionType: Type;\n\n  /**\n   * The target resource of the permission. The shape of this string depends on\n   * the permission type. For example, a restricted method target key will\n   * consist of either a complete method name or the prefix of a namespaced\n   * method, e.g. `wallet_snap_*`.\n   */\n  targetKey: string;\n\n  /**\n   * An array of the caveat types that may be added to instances of this\n   * permission.\n   */\n  allowedCaveats: Readonly<NonEmptyArray<string>> | null;\n\n  /**\n   * The factory function used to get permission objects. Permissions returned\n   * by this function are presumed to valid, and they will not be passed to the\n   * validator function associated with this specification (if any). In other\n   * words, the factory function should validate the permissions it creates.\n   *\n   * If no factory is specified, the {@link Permission} constructor will be\n   * used, and the validator function (if specified) will be called on newly\n   * constructed permissions.\n   */\n  factory?: PermissionFactory<any, Record<string, unknown>>;\n\n  /**\n   * The validator function used to validate permissions of the associated type\n   * whenever they are mutated. The only way a permission can be legally mutated\n   * is when its caveats are modified by the permission controller.\n   *\n   * The validator should throw an appropriate JSON-RPC error if validation fails.\n   */\n  validator?: PermissionValidatorConstraint;\n\n  /**\n   * The side-effect triggered by the {@link PermissionController} once the user approved it.\n   * The side-effect can only be an action allowed to be called inside the {@link PermissionController}.\n   *\n   * If the side-effect action fails, the permission that triggered it is revoked.\n   */\n  sideEffect?: PermissionSideEffect<any, any>;\n\n  /**\n   * The Permission may be available to only a subset of the subject types. If so, specify the subject types as an array.\n   * If a subject with a type not in this array tries to request the permission, the call will fail.\n   *\n   * Leaving this as undefined uses default behaviour where the permission is available to request for all subject types.\n   */\n  subjectTypes?: readonly SubjectType[];\n};\n\n/**\n * The constraint for restricted method permission specification objects.\n * Permissions that correspond to JSON-RPC methods are specified using objects\n * that conform to this type.\n *\n * See the README for more details.\n */\nexport type RestrictedMethodSpecificationConstraint =\n  PermissionSpecificationBase<PermissionType.RestrictedMethod> & {\n    /**\n     * The implementation of the restricted method that the permission\n     * corresponds to.\n     */\n    methodImplementation: RestrictedMethod<any, any>;\n  };\n\n/**\n * The constraint for endowment permission specification objects. Permissions\n * that endow callers with some restricted resource are specified using objects\n * that conform to this type.\n *\n * See the README for more details.\n */\nexport type EndowmentSpecificationConstraint =\n  PermissionSpecificationBase<PermissionType.Endowment> & {\n    /**\n     * The {@link EndowmentGetter} function for the permission. This function\n     * will be called by the {@link PermissionController} whenever the\n     * permission is invoked, after which the host can apply the endowments to\n     * the requesting subject in the intended manner.\n     */\n    endowmentGetter: EndowmentGetter<any>;\n  };\n\n/**\n * The constraint for permission specification objects. Every {@link Permission}\n * supported by a {@link PermissionController} must have an associated\n * specification, which is the source of truth for all permission-related types.\n * All specifications must adhere to the {@link PermissionSpecificationBase}\n * interface, but specifications may have different fields depending on the\n * {@link PermissionType}.\n *\n * See the README for more details.\n */\nexport type PermissionSpecificationConstraint =\n  | EndowmentSpecificationConstraint\n  | RestrictedMethodSpecificationConstraint;\n\n/**\n * Options for {@link PermissionSpecificationBuilder} functions.\n */\ntype PermissionSpecificationBuilderOptions<\n  FactoryHooks extends Record<string, unknown>,\n  MethodHooks extends Record<string, unknown>,\n  ValidatorHooks extends Record<string, unknown>,\n> = {\n  targetKey?: string;\n  allowedCaveats?: Readonly<NonEmptyArray<string>> | null;\n  factoryHooks?: FactoryHooks;\n  methodHooks?: MethodHooks;\n  validatorHooks?: ValidatorHooks;\n};\n\n/**\n * A function that builds a permission specification. Modules that specify\n * permissions for external consumption should make this their primary /\n * default export so that host applications can use them to generate concrete\n * specifications tailored to their requirements.\n */\nexport type PermissionSpecificationBuilder<\n  Type extends PermissionType,\n  Options extends PermissionSpecificationBuilderOptions<any, any, any>,\n  Specification extends PermissionSpecificationConstraint & {\n    permissionType: Type;\n  },\n> = (options: Options) => Specification;\n\n/**\n * A restricted method permission export object, containing the\n * {@link PermissionSpecificationBuilder} function and \"hook name\" objects.\n */\nexport type PermissionSpecificationBuilderExportConstraint = {\n  targetKey: string;\n  specificationBuilder: PermissionSpecificationBuilder<\n    PermissionType,\n    PermissionSpecificationBuilderOptions<any, any, any>,\n    PermissionSpecificationConstraint\n  >;\n  factoryHookNames?: Record<string, true>;\n  methodHookNames?: Record<string, true>;\n  validatorHookNames?: Record<string, true>;\n};\n\ntype ValidRestrictedMethodSpecification<\n  Specification extends RestrictedMethodSpecificationConstraint,\n> = Specification['methodImplementation'] extends ValidRestrictedMethod<\n  Specification['methodImplementation']\n>\n  ? Specification\n  : never;\n\n/**\n * Constraint for {@link PermissionSpecificationConstraint} objects that\n * evaluates to `never` if the specification contains any invalid fields.\n *\n * @template Specification - The permission specification to validate.\n */\nexport type ValidPermissionSpecification<\n  Specification extends PermissionSpecificationConstraint,\n> = Specification['targetKey'] extends ValidTargetKey<\n  Specification['targetKey']\n>\n  ? Specification['permissionType'] extends PermissionType.Endowment\n    ? Specification\n    : Specification['permissionType'] extends PermissionType.RestrictedMethod\n    ? ValidRestrictedMethodSpecification<\n        Extract<Specification, RestrictedMethodSpecificationConstraint>\n      >\n    : never\n  : never;\n\n/**\n * Checks that the specification has the expected permission type.\n *\n * @param specification - The specification to check.\n * @param expectedType - The expected permission type.\n * @template Specification - The specification to check.\n * @template Type - The expected permission type.\n * @returns Whether or not the specification is of the expected type.\n */\nexport function hasSpecificationType<\n  Specification extends PermissionSpecificationConstraint,\n  Type extends PermissionType,\n>(\n  specification: Specification,\n  expectedType: Type,\n): specification is Specification & {\n  permissionType: Type;\n} {\n  return specification.permissionType === expectedType;\n}\n\n/**\n * The specifications for all permissions supported by a particular\n * {@link PermissionController}.\n *\n * @template Specifications - The union of all {@link PermissionSpecificationConstraint} types.\n */\nexport type PermissionSpecificationMap<\n  Specification extends PermissionSpecificationConstraint,\n> = {\n  [TargetKey in Specification['targetKey']]: Specification extends {\n    targetKey: TargetKey;\n  }\n    ? Specification\n    : never;\n};\n\n/**\n * Extracts a specific {@link PermissionSpecificationConstraint} from a union of\n * permission specifications.\n *\n * @template Specification - The specification union type to extract from.\n * @template TargetKey - The `targetKey` of the specification to extract.\n */\nexport type ExtractPermissionSpecification<\n  Specification extends PermissionSpecificationConstraint,\n  TargetKey extends Specification['targetKey'],\n> = Specification extends {\n  targetKey: TargetKey;\n}\n  ? Specification\n  : never;\n"]}

package/dist/PermissionController.d.ts

@@ -1,9 +1,10 @@
 import { Patch } from 'immer';
 import { AcceptRequest as AcceptApprovalRequest, AddApprovalRequest, HasApprovalRequest, RejectRequest as RejectApprovalRequest } from '@metamask/approval-controller';
-import { BaseControllerV2, RestrictedControllerMessenger } from '@metamask/base-controller';
+import { BaseControllerV2, RestrictedControllerMessenger, ActionConstraint, EventConstraint } from '@metamask/base-controller';
 import { Json, NonEmptyArray } from '@metamask/controller-utils';
+import { GetSubjectMetadata } from './SubjectMetadataController';
 import { CaveatConstraint, CaveatSpecificationConstraint, CaveatSpecificationMap, ExtractCaveat, ExtractCaveats, ExtractCaveatValue } from './Caveat';
-import { EndowmentSpecificationConstraint, ExtractAllowedCaveatTypes, OriginString, PermissionConstraint, PermissionSpecificationConstraint, PermissionSpecificationMap, RequestedPermissions, RestrictedMethod, RestrictedMethodParameters, RestrictedMethodSpecificationConstraint, ValidPermission, ValidPermissionSpecification } from './Permission';
+import { EndowmentSpecificationConstraint, ExtractAllowedCaveatTypes, OriginString, PermissionConstraint, PermissionSpecificationConstraint, PermissionSpecificationMap, RequestedPermissions, RestrictedMethod, RestrictedMethodParameters, RestrictedMethodSpecificationConstraint, SideEffectHandler, ValidPermission, ValidPermissionSpecification } from './Permission';
 import { getPermissionMiddlewareFactory } from './permission-middleware';
 /**
  * Metadata associated with {@link PermissionController} subjects.
@@ -30,6 +31,10 @@ export declare type PermissionsRequest = {
     permissions: RequestedPermissions;
     [key: string]: Json;
 };
+export declare type SideEffects = {
+    permittedHandlers: Record<string, SideEffectHandler<any, any>>;
+    failureHandlers: Record<string, SideEffectHandler<any, any>>;
+};
 /**
  * The name of the {@link PermissionController}.
  */
@@ -175,11 +180,12 @@ export declare type PermissionControllerEvents = PermissionControllerStateChange
  * The external {@link ControllerMessenger} actions available to the
  * {@link PermissionController}.
  */
-declare type AllowedActions = AddApprovalRequest | HasApprovalRequest | AcceptApprovalRequest | RejectApprovalRequest;
+declare type AllowedActions = AddApprovalRequest | HasApprovalRequest | AcceptApprovalRequest | RejectApprovalRequest | GetSubjectMetadata;
 /**
  * The messenger of the {@link PermissionController}.
  */
 export declare type PermissionControllerMessenger = RestrictedControllerMessenger<typeof controllerName, PermissionControllerActions | AllowedActions, PermissionControllerEvents, AllowedActions['type'], never>;
+export declare type SideEffectMessenger<Actions extends ActionConstraint, Events extends EventConstraint> = RestrictedControllerMessenger<typeof controllerName, Actions, Events, string, never>;
 /**
  * A generic {@link PermissionController}.
  */
@@ -650,6 +656,7 @@ export declare class PermissionController<ControllerPermissionSpecification exte
     }): SubjectPermissions<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>;
     /**
      * Validates the specified permission by:
+     * - Ensuring that if `subjectTypes` is specified, the subject requesting the permission is of a type in the list.
      * - Ensuring that its `caveats` property is either `null` or a non-empty array.
      * - Ensuring that it only includes caveats allowed by its specification.
      * - Ensuring that it includes no duplicate caveats (by caveat type).
@@ -735,6 +742,7 @@ export declare class PermissionController<ControllerPermissionSpecification exte
     }): Promise<[
         SubjectPermissions<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>,
         {
+            data?: Record<string, unknown>;
             id: string;
             origin: OriginString;
         }
@@ -764,6 +772,22 @@ export declare class PermissionController<ControllerPermissionSpecification exte
      * @returns The approved permissions request object.
      */
     private requestUserApproval;
+    /**
+     * Reunites all the side-effects (onPermitted and onFailure) of the requested permissions inside a record of arrays.
+     *
+     * @param permissions - The approved permissions.
+     * @returns The {@link SideEffects} object containing the handlers arrays.
+     */
+    private getSideEffects;
+    /**
+     * Executes the side-effects of the approved permissions while handling the errors if any.
+     * It will pass an instance of the {@link messagingSystem} and the request data associated with the permission request to the handlers through its params.
+     *
+     * @param sideEffects - the side-effect record created by {@link getSideEffects}
+     * @param requestData - the permissions requestData.
+     * @returns the value returned by all the `onPermitted` handlers in an array.
+     */
+    private executeSideEffects;
     /**
      * Validates an approved {@link PermissionsRequest} object. The approved
      * request must have the required `metadata` and `permissions` properties,
@@ -875,3 +899,4 @@ export declare class PermissionController<ControllerPermissionSpecification exte
     private _executeRestrictedMethod;
 }
 export {};
+//# sourceMappingURL=PermissionController.d.ts.map

package/dist/PermissionController.d.ts.map

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

package/dist/PermissionController.js

@@ -792,6 +792,7 @@ class PermissionController extends base_controller_1.BaseControllerV2 {
     }
     /**
      * Validates the specified permission by:
+     * - Ensuring that if `subjectTypes` is specified, the subject requesting the permission is of a type in the list.
      * - Ensuring that its `caveats` property is either `null` or a non-empty array.
      * - Ensuring that it only includes caveats allowed by its specification.
      * - Ensuring that it includes no duplicate caveats (by caveat type).
@@ -815,7 +816,19 @@ class PermissionController extends base_controller_1.BaseControllerV2 {
         invokePermissionValidator: true,
         performCaveatValidation: true,
     }) {
+        var _a;
         const { allowedCaveats, validator } = specification;
+        if (((_a = specification.subjectTypes) === null || _a === void 0 ? void 0 : _a.length) &&
+            specification.subjectTypes.length > 0) {
+            const metadata = this.messagingSystem.call('SubjectMetadataController:getSubjectMetadata', origin);
+            if (!metadata ||
+                metadata.subjectType === null ||
+                !specification.subjectTypes.includes(metadata.subjectType)) {
+                throw specification.permissionType === Permission_1.PermissionType.RestrictedMethod
+                    ? (0, errors_1.methodNotFound)(targetName, { origin })
+                    : new errors_1.EndowmentPermissionDoesNotExistError(targetName, origin);
+            }
+        }
         if ((0, controller_utils_1.hasProperty)(permission, 'caveats')) {
             const { caveats } = permission;
             if (caveats !== null && !(Array.isArray(caveats) && caveats.length > 0)) {
@@ -951,7 +964,22 @@ class PermissionController extends base_controller_1.BaseControllerV2 {
                 metadata,
                 permissions: requestedPermissions,
             };
-            const _a = yield this.requestUserApproval(permissionsRequest), { permissions: approvedPermissions } = _a, requestData = __rest(_a, ["permissions"]);
+            const approvedRequest = yield this.requestUserApproval(permissionsRequest);
+            const { permissions: approvedPermissions } = approvedRequest, requestData = __rest(approvedRequest, ["permissions"]);
+            const sideEffects = this.getSideEffects(approvedPermissions);
+            if (Object.values(sideEffects.permittedHandlers).length > 0) {
+                const sideEffectsData = yield this.executeSideEffects(sideEffects, approvedRequest);
+                const mappedData = Object.keys(sideEffects.permittedHandlers).reduce((acc, permission, i) => (Object.assign({ [permission]: sideEffectsData[i] }, acc)), {});
+                return [
+                    this.grantPermissions({
+                        subject,
+                        approvedPermissions,
+                        preserveExistingPermissions,
+                        requestData,
+                    }),
+                    Object.assign({ data: mappedData }, metadata),
+                ];
+            }
             return [
                 this.grantPermissions({
                     subject,
@@ -1033,6 +1061,69 @@ class PermissionController extends base_controller_1.BaseControllerV2 {
             return approvedRequest;
         });
     }
+    /**
+     * Reunites all the side-effects (onPermitted and onFailure) of the requested permissions inside a record of arrays.
+     *
+     * @param permissions - The approved permissions.
+     * @returns The {@link SideEffects} object containing the handlers arrays.
+     */
+    getSideEffects(permissions) {
+        return Object.keys(permissions).reduce((sideEffectList, targetName) => {
+            const targetKey = this.getTargetKey(targetName);
+            if (targetKey) {
+                const specification = this.getPermissionSpecification(targetKey);
+                if (specification.sideEffect) {
+                    sideEffectList.permittedHandlers[targetName] =
+                        specification.sideEffect.onPermitted;
+                    if (specification.sideEffect.onFailure) {
+                        sideEffectList.failureHandlers[targetName] =
+                            specification.sideEffect.onFailure;
+                    }
+                }
+            }
+            return sideEffectList;
+        }, { permittedHandlers: {}, failureHandlers: {} });
+    }
+    /**
+     * Executes the side-effects of the approved permissions while handling the errors if any.
+     * It will pass an instance of the {@link messagingSystem} and the request data associated with the permission request to the handlers through its params.
+     *
+     * @param sideEffects - the side-effect record created by {@link getSideEffects}
+     * @param requestData - the permissions requestData.
+     * @returns the value returned by all the `onPermitted` handlers in an array.
+     */
+    executeSideEffects(sideEffects, requestData) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { permittedHandlers, failureHandlers } = sideEffects;
+            const params = {
+                requestData,
+                messagingSystem: this.messagingSystem,
+            };
+            const promiseResults = yield Promise.allSettled(Object.values(permittedHandlers).map((permittedHandler) => permittedHandler(params)));
+            // lib.es2020.promise.d.ts does not export its types so we're using a simple type.
+            const rejectedHandlers = promiseResults.filter((promise) => promise.status === 'rejected');
+            if (rejectedHandlers.length > 0) {
+                const failureHandlersList = Object.values(failureHandlers);
+                if (failureHandlersList.length > 0) {
+                    try {
+                        yield Promise.all(failureHandlersList.map((failureHandler) => failureHandler(params)));
+                    }
+                    catch (error) {
+                        throw (0, errors_1.internalError)('Unexpected error in side-effects', { error });
+                    }
+                }
+                const reasons = rejectedHandlers.map((handler) => handler.reason);
+                reasons.forEach((reason) => {
+                    console.error(reason);
+                });
+                throw reasons.length > 1
+                    ? (0, errors_1.internalError)('Multiple errors occurred during side-effects execution', { errors: reasons })
+                    : reasons[0];
+            }
+            // lib.es2020.promise.d.ts does not export its types so we're using a simple type.
+            return promiseResults.map(({ value }) => value);
+        });
+    }
     /**
      * Validates an approved {@link PermissionsRequest} object. The approved
      * request must have the required `metadata` and `permissions` properties,