@metamask/permission-controller 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0]
+### Added
+- Initial release
+  - As a result of converting our shared controllers repo into a monorepo ([#831](https://github.com/MetaMask/controllers/pull/831)), we've created this package from select parts of [`@metamask/controllers` v33.0.0](https://github.com/MetaMask/controllers/tree/v33.0.0), namely:
+    - Everything in `src/permissions`
+
+    All changes listed after this point were applied to this package following the monorepo conversion.
+
+[Unreleased]: https://github.com/MetaMask/controllers/compare/@metamask/permission-controller@1.0.0...HEAD
+[1.0.0]: https://github.com/MetaMask/controllers/releases/tag/@metamask/permission-controller@1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2018 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

package/README.md

@@ -0,0 +1,19 @@
+# `@metamask/permission-controller`
+
+Mediates access to JSON-RPC methods, used to interact with pieces of the MetaMask stack, via middleware for `json-rpc-engine`.
+
+## Installation
+
+`yarn add @metamask/permission-controller`
+
+or
+
+`npm install @metamask/permission-controller`
+
+## Understanding
+
+Please read the [Architecture][./architecture.md] document for more on how PermissionController works and how to use it.
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/controllers#readme).

package/dist/Caveat.d.ts

@@ -0,0 +1,182 @@
+import { Json } from '@metamask/types';
+import { AsyncRestrictedMethod, RestrictedMethod, PermissionConstraint, RestrictedMethodParameters } from './Permission';
+export declare type CaveatConstraint = {
+    /**
+     * The type of the caveat. The type is presumed to be meaningful in the
+     * context of the capability it is associated with.
+     *
+     * In MetaMask, every permission can only have one caveat of each type.
+     */
+    readonly type: string;
+    /**
+     * Any additional data necessary to enforce the caveat.
+     */
+    readonly value: Json;
+};
+/**
+ * A `ZCAP-LD`-like caveat object. A caveat is associated with a particular
+ * permission, and stored in its `caveats` array. Conceptually, a caveat is
+ * an arbitrary attenuation of the authority granted by its associated
+ * permission. It is the responsibility of the host to interpret and apply
+ * the restriction represented by a caveat.
+ *
+ * @template Type - The type of the caveat.
+ * @template Value - The value associated with the caveat.
+ */
+export declare type Caveat<Type extends string, Value extends Json> = {
+    /**
+     * The type of the caveat. The type is presumed to be meaningful in the
+     * context of the capability it is associated with.
+     *
+     * In MetaMask, every permission can only have one caveat of each type.
+     */
+    readonly type: Type;
+    /**
+     * Any additional data necessary to enforce the caveat.
+     */
+    readonly value: Value;
+};
+/**
+ * A function for applying caveats to a restricted method request.
+ *
+ * @template ParentCaveat - The caveat type associated with this decorator.
+ * @param decorated - The restricted method implementation to be decorated.
+ * The method may have already been decorated with other caveats.
+ * @param caveat - The caveat object.
+ * @returns The decorated restricted method implementation.
+ */
+export declare type CaveatDecorator<ParentCaveat extends CaveatConstraint> = (decorated: AsyncRestrictedMethod<RestrictedMethodParameters, Json>, caveat: ParentCaveat) => AsyncRestrictedMethod<RestrictedMethodParameters, Json>;
+/**
+ * Extracts a caveat value type from a caveat decorator.
+ *
+ * @template Decorator - The {@link CaveatDecorator} to extract a caveat value
+ * type from.
+ */
+declare type ExtractCaveatValueFromDecorator<Decorator extends CaveatDecorator<any>> = Decorator extends (decorated: any, caveat: infer ParentCaveat) => AsyncRestrictedMethod<any, any> ? ParentCaveat extends CaveatConstraint ? ParentCaveat['value'] : never : never;
+/**
+ * A function for validating caveats of a particular type.
+ *
+ * @template ParentCaveat - The caveat type associated with this validator.
+ * @param caveat - The caveat object to validate.
+ * @param origin - The origin associated with the parent permission.
+ * @param target - The target of the parent permission.
+ */
+export declare type CaveatValidator<ParentCaveat extends CaveatConstraint> = (caveat: {
+    type: ParentCaveat['type'];
+    value: unknown;
+}, origin?: string, target?: string) => void;
+export declare type CaveatSpecificationBase = {
+    /**
+     * The string type of the caveat.
+     */
+    type: string;
+    /**
+     * The validator function used to validate caveats of the associated type
+     * whenever they are instantiated. Caveat are instantiated whenever they are
+     * created or mutated.
+     *
+     * The validator should throw an appropriate JSON-RPC error if validation fails.
+     *
+     * If no validator is specified, no validation of caveat values will be
+     * performed. Although caveats can also be validated by permission validators,
+     * validating caveat values separately is strongly recommended.
+     */
+    validator?: CaveatValidator<any>;
+};
+export declare type RestrictedMethodCaveatSpecificationConstraint = CaveatSpecificationBase & {
+    /**
+     * The decorator function used to apply the caveat to restricted method
+     * requests.
+     */
+    decorator: CaveatDecorator<any>;
+};
+export declare type EndowmentCaveatSpecificationConstraint = CaveatSpecificationBase;
+/**
+ * The constraint for caveat specification objects. Every {@link Caveat}
+ * supported by a {@link PermissionController} must have an associated
+ * specification, which is the source of truth for all caveat-related types.
+ * In addition, a caveat specification may include a decorator function used
+ * to apply the caveat's attenuation to a restricted method. It may also include
+ * a validator function specified by the consumer.
+ *
+ * See the README for more details.
+ */
+export declare type CaveatSpecificationConstraint = RestrictedMethodCaveatSpecificationConstraint | EndowmentCaveatSpecificationConstraint;
+/**
+ * Options for {@link CaveatSpecificationBuilder} functions.
+ */
+declare type CaveatSpecificationBuilderOptions<DecoratorHooks extends Record<string, unknown>, ValidatorHooks extends Record<string, unknown>> = {
+    type?: string;
+    decoratorHooks?: DecoratorHooks;
+    validatorHooks?: ValidatorHooks;
+};
+/**
+ * A function that builds caveat specifications. Modules that specify caveats
+ * for external consumption should make this their primary / default export so
+ * that host applications can use them to generate concrete specifications
+ * tailored to their requirements.
+ */
+export declare type CaveatSpecificationBuilder<Options extends CaveatSpecificationBuilderOptions<any, any>, Specification extends CaveatSpecificationConstraint> = (options: Options) => Specification;
+/**
+ * A caveat specification export object, containing the
+ * {@link CaveatSpecificationBuilder} function and "hook name" objects.
+ */
+export declare type CaveatSpecificationBuilderExportConstraint = {
+    specificationBuilder: CaveatSpecificationBuilder<CaveatSpecificationBuilderOptions<any, any>, CaveatSpecificationConstraint>;
+    decoratorHookNames?: Record<string, true>;
+    validatorHookNames?: Record<string, true>;
+};
+/**
+ * The specifications for all caveats supported by a particular
+ * {@link PermissionController}.
+ *
+ * @template Specifications - The union of all {@link CaveatSpecificationConstraint} types.
+ */
+export declare type CaveatSpecificationMap<CaveatSpecification extends CaveatSpecificationConstraint> = Record<CaveatSpecification['type'], CaveatSpecification>;
+/**
+ * Extracts the union of all caveat types specified by the given
+ * {@link CaveatSpecificationConstraint} type.
+ *
+ * @template CaveatSpecification - The {@link CaveatSpecificationConstraint} to extract a
+ * caveat type union from.
+ */
+export declare type ExtractCaveats<CaveatSpecification extends CaveatSpecificationConstraint> = CaveatSpecification extends any ? CaveatSpecification extends RestrictedMethodCaveatSpecificationConstraint ? Caveat<CaveatSpecification['type'], ExtractCaveatValueFromDecorator<RestrictedMethodCaveatSpecificationConstraint['decorator']>> : Caveat<CaveatSpecification['type'], Json> : never;
+/**
+ * Extracts the type of a specific {@link Caveat} from a union of caveat
+ * specifications.
+ *
+ * @template CaveatSpecifications - The union of all caveat specifications.
+ * @template CaveatType - The type of the caveat to extract.
+ */
+export declare type ExtractCaveat<CaveatSpecifications extends CaveatSpecificationConstraint, CaveatType extends string> = Extract<ExtractCaveats<CaveatSpecifications>, {
+    type: CaveatType;
+}>;
+/**
+ * Extracts the value type of a specific {@link Caveat} from a union of caveat
+ * specifications.
+ *
+ * @template CaveatSpecifications - The union of all caveat specifications.
+ * @template CaveatType - The type of the caveat whose value to extract.
+ */
+export declare type ExtractCaveatValue<CaveatSpecifications extends CaveatSpecificationConstraint, CaveatType extends string> = ExtractCaveat<CaveatSpecifications, CaveatType>['value'];
+/**
+ * Determines whether a caveat specification is a restricted method caveat specification.
+ *
+ * @param specification - The caveat specification.
+ * @returns True if the caveat specification is a restricted method caveat specification, otherwise false.
+ */
+export declare function isRestrictedMethodCaveatSpecification(specification: CaveatSpecificationConstraint): specification is RestrictedMethodCaveatSpecificationConstraint;
+/**
+ * Decorate a restricted method implementation with its caveats.
+ *
+ * Note that all caveat functions (i.e. the argument and return value of the
+ * decorator) must be awaited.
+ *
+ * @param methodImplementation - The restricted method implementation
+ * @param permission - The origin's potential permission
+ * @param caveatSpecifications - All caveat implementations
+ * @returns The decorated method implementation
+ */
+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 {};

package/dist/Caveat.js

@@ -0,0 +1,57 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decorateWithCaveats = exports.isRestrictedMethodCaveatSpecification = void 0;
+const controller_utils_1 = require("@metamask/controller-utils");
+const errors_1 = require("./errors");
+const Permission_1 = require("./Permission");
+/**
+ * Determines whether a caveat specification is a restricted method caveat specification.
+ *
+ * @param specification - The caveat specification.
+ * @returns True if the caveat specification is a restricted method caveat specification, otherwise false.
+ */
+function isRestrictedMethodCaveatSpecification(specification) {
+    return (0, controller_utils_1.hasProperty)(specification, 'decorator');
+}
+exports.isRestrictedMethodCaveatSpecification = isRestrictedMethodCaveatSpecification;
+/**
+ * Decorate a restricted method implementation with its caveats.
+ *
+ * Note that all caveat functions (i.e. the argument and return value of the
+ * decorator) must be awaited.
+ *
+ * @param methodImplementation - The restricted method implementation
+ * @param permission - The origin's potential permission
+ * @param caveatSpecifications - All caveat implementations
+ * @returns The decorated method implementation
+ */
+function decorateWithCaveats(methodImplementation, permission, // bound to the requesting origin
+caveatSpecifications) {
+    const { caveats } = permission;
+    if (!caveats) {
+        return methodImplementation;
+    }
+    let decorated = (args) => __awaiter(this, void 0, void 0, function* () { return methodImplementation(args); });
+    for (const caveat of caveats) {
+        const specification = caveatSpecifications[caveat.type];
+        if (!specification) {
+            throw new errors_1.UnrecognizedCaveatTypeError(caveat.type);
+        }
+        if (!isRestrictedMethodCaveatSpecification(specification)) {
+            throw new errors_1.CaveatSpecificationMismatchError(specification, Permission_1.PermissionType.RestrictedMethod);
+        }
+        decorated = specification.decorator(decorated, caveat);
+    }
+    return decorated;
+}
+exports.decorateWithCaveats = decorateWithCaveats;
+//# sourceMappingURL=Caveat.js.map

package/dist/Caveat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Caveat.js","sourceRoot":"","sources":["../src/Caveat.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,iEAAyD;AACzD,qCAGkB;AAClB,6CAMsB;AAsOtB;;;;;GAKG;AACH,SAAgB,qCAAqC,CACnD,aAA4C;IAE5C,OAAO,IAAA,8BAAW,EAAC,aAAa,EAAE,WAAW,CAAC,CAAC;AACjD,CAAC;AAJD,sFAIC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAGjC,oBAAwE,EACxE,UAA0C,EAAE,iCAAiC;AAC7E,oBAAkE;IAElE,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,CAAC;IAC/B,IAAI,CAAC,OAAO,EAAE;QACZ,OAAO,oBAAoB,CAAC;KAC7B;IAED,IAAI,SAAS,GAAG,CACd,IAAuE,EACvE,EAAE,gDAAC,OAAA,oBAAoB,CAAC,IAAI,CAAC,CAAA,GAAA,CAAC;IAEhC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE;QAC5B,MAAM,aAAa,GACjB,oBAAoB,CAAC,MAAM,CAAC,IAAoC,CAAC,CAAC;QACpE,IAAI,CAAC,aAAa,EAAE;YAClB,MAAM,IAAI,oCAA2B,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;SACpD;QAED,IAAI,CAAC,qCAAqC,CAAC,aAAa,CAAC,EAAE;YACzD,MAAM,IAAI,yCAAgC,CACxC,aAAa,EACb,2BAAc,CAAC,gBAAgB,CAChC,CAAC;SACH;QACD,SAAS,GAAG,aAAa,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;KACxD;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAjCD,kDAiCC","sourcesContent":["import { Json } from '@metamask/types';\nimport { hasProperty } from '@metamask/controller-utils';\nimport {\n  CaveatSpecificationMismatchError,\n  UnrecognizedCaveatTypeError,\n} from './errors';\nimport {\n  AsyncRestrictedMethod,\n  RestrictedMethod,\n  PermissionConstraint,\n  RestrictedMethodParameters,\n  PermissionType,\n} from './Permission';\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\nimport type { PermissionController } from './PermissionController';\n\nexport type CaveatConstraint = {\n  /**\n   * The type of the caveat. The type is presumed to be meaningful in the\n   * context of the capability it is associated with.\n   *\n   * In MetaMask, every permission can only have one caveat of each type.\n   */\n  readonly type: string;\n\n  // TODO:TS4.4 Make optional\n  /**\n   * Any additional data necessary to enforce the caveat.\n   */\n  readonly value: Json;\n};\n\n/**\n * A `ZCAP-LD`-like caveat object. A caveat is associated with a particular\n * permission, and stored in its `caveats` array. Conceptually, a caveat is\n * an arbitrary attenuation of the authority granted by its associated\n * permission. It is the responsibility of the host to interpret and apply\n * the restriction represented by a caveat.\n *\n * @template Type - The type of the caveat.\n * @template Value - The value associated with the caveat.\n */\nexport type Caveat<Type extends string, Value extends Json> = {\n  /**\n   * The type of the caveat. The type is presumed to be meaningful in the\n   * context of the capability it is associated with.\n   *\n   * In MetaMask, every permission can only have one caveat of each type.\n   */\n  readonly type: Type;\n\n  // TODO:TS4.4 Make optional\n  /**\n   * Any additional data necessary to enforce the caveat.\n   */\n  readonly value: Value;\n};\n\n// Next, we define types used for specifying caveats at the consumer layer,\n// and a function for applying caveats to a restricted method request. This is\n// Accomplished by decorating the restricted method implementation with the\n// the corresponding caveat functions.\n\n/**\n * A function for applying caveats to a restricted method request.\n *\n * @template ParentCaveat - The caveat type associated with this decorator.\n * @param decorated - The restricted method implementation to be decorated.\n * The method may have already been decorated with other caveats.\n * @param caveat - The caveat object.\n * @returns The decorated restricted method implementation.\n */\nexport type CaveatDecorator<ParentCaveat extends CaveatConstraint> = (\n  decorated: AsyncRestrictedMethod<RestrictedMethodParameters, Json>,\n  caveat: ParentCaveat,\n) => AsyncRestrictedMethod<RestrictedMethodParameters, Json>;\n\n/**\n * Extracts a caveat value type from a caveat decorator.\n *\n * @template Decorator - The {@link CaveatDecorator} to extract a caveat value\n * type from.\n */\ntype ExtractCaveatValueFromDecorator<Decorator extends CaveatDecorator<any>> =\n  Decorator extends (\n    decorated: any,\n    caveat: infer ParentCaveat,\n  ) => AsyncRestrictedMethod<any, any>\n    ? ParentCaveat extends CaveatConstraint\n      ? ParentCaveat['value']\n      : never\n    : never;\n\n/**\n * A function for validating caveats of a particular type.\n *\n * @template ParentCaveat - The caveat type associated with this validator.\n * @param caveat - The caveat object to validate.\n * @param origin - The origin associated with the parent permission.\n * @param target - The target of the parent permission.\n */\nexport type CaveatValidator<ParentCaveat extends CaveatConstraint> = (\n  caveat: { type: ParentCaveat['type']; value: unknown },\n  origin?: string,\n  target?: string,\n) => void;\n\nexport type CaveatSpecificationBase = {\n  /**\n   * The string type of the caveat.\n   */\n  type: string;\n\n  /**\n   * The validator function used to validate caveats of the associated type\n   * whenever they are instantiated. Caveat are instantiated whenever they are\n   * created or mutated.\n   *\n   * The validator should throw an appropriate JSON-RPC error if validation fails.\n   *\n   * If no validator is specified, no validation of caveat values will be\n   * performed. Although caveats can also be validated by permission validators,\n   * validating caveat values separately is strongly recommended.\n   */\n  validator?: CaveatValidator<any>;\n};\n\nexport type RestrictedMethodCaveatSpecificationConstraint =\n  CaveatSpecificationBase & {\n    /**\n     * The decorator function used to apply the caveat to restricted method\n     * requests.\n     */\n    decorator: CaveatDecorator<any>;\n  };\n\nexport type EndowmentCaveatSpecificationConstraint = CaveatSpecificationBase;\n\n/**\n * The constraint for caveat specification objects. Every {@link Caveat}\n * supported by a {@link PermissionController} must have an associated\n * specification, which is the source of truth for all caveat-related types.\n * In addition, a caveat specification may include a decorator function used\n * to apply the caveat's attenuation to a restricted method. It may also include\n * a validator function specified by the consumer.\n *\n * See the README for more details.\n */\nexport type CaveatSpecificationConstraint =\n  | RestrictedMethodCaveatSpecificationConstraint\n  | EndowmentCaveatSpecificationConstraint;\n\n/**\n * Options for {@link CaveatSpecificationBuilder} functions.\n */\ntype CaveatSpecificationBuilderOptions<\n  DecoratorHooks extends Record<string, unknown>,\n  ValidatorHooks extends Record<string, unknown>,\n> = {\n  type?: string;\n  decoratorHooks?: DecoratorHooks;\n  validatorHooks?: ValidatorHooks;\n};\n\n/**\n * A function that builds caveat specifications. Modules that specify caveats\n * for external consumption should make this their primary / default export so\n * that host applications can use them to generate concrete specifications\n * tailored to their requirements.\n */\nexport type CaveatSpecificationBuilder<\n  Options extends CaveatSpecificationBuilderOptions<any, any>,\n  Specification extends CaveatSpecificationConstraint,\n> = (options: Options) => Specification;\n\n/**\n * A caveat specification export object, containing the\n * {@link CaveatSpecificationBuilder} function and \"hook name\" objects.\n */\nexport type CaveatSpecificationBuilderExportConstraint = {\n  specificationBuilder: CaveatSpecificationBuilder<\n    CaveatSpecificationBuilderOptions<any, any>,\n    CaveatSpecificationConstraint\n  >;\n  decoratorHookNames?: Record<string, true>;\n  validatorHookNames?: Record<string, true>;\n};\n\n/**\n * The specifications for all caveats supported by a particular\n * {@link PermissionController}.\n *\n * @template Specifications - The union of all {@link CaveatSpecificationConstraint} types.\n */\nexport type CaveatSpecificationMap<\n  CaveatSpecification extends CaveatSpecificationConstraint,\n> = Record<CaveatSpecification['type'], CaveatSpecification>;\n\n/**\n * Extracts the union of all caveat types specified by the given\n * {@link CaveatSpecificationConstraint} type.\n *\n * @template CaveatSpecification - The {@link CaveatSpecificationConstraint} to extract a\n * caveat type union from.\n */\nexport type ExtractCaveats<\n  CaveatSpecification extends CaveatSpecificationConstraint,\n> = CaveatSpecification extends any\n  ? CaveatSpecification extends RestrictedMethodCaveatSpecificationConstraint\n    ? Caveat<\n        CaveatSpecification['type'],\n        ExtractCaveatValueFromDecorator<\n          RestrictedMethodCaveatSpecificationConstraint['decorator']\n        >\n      >\n    : Caveat<CaveatSpecification['type'], Json>\n  : never;\n\n/**\n * Extracts the type of a specific {@link Caveat} from a union of caveat\n * specifications.\n *\n * @template CaveatSpecifications - The union of all caveat specifications.\n * @template CaveatType - The type of the caveat to extract.\n */\nexport type ExtractCaveat<\n  CaveatSpecifications extends CaveatSpecificationConstraint,\n  CaveatType extends string,\n> = Extract<ExtractCaveats<CaveatSpecifications>, { type: CaveatType }>;\n\n/**\n * Extracts the value type of a specific {@link Caveat} from a union of caveat\n * specifications.\n *\n * @template CaveatSpecifications - The union of all caveat specifications.\n * @template CaveatType - The type of the caveat whose value to extract.\n */\nexport type ExtractCaveatValue<\n  CaveatSpecifications extends CaveatSpecificationConstraint,\n  CaveatType extends string,\n> = ExtractCaveat<CaveatSpecifications, CaveatType>['value'];\n\n/**\n * Determines whether a caveat specification is a restricted method caveat specification.\n *\n * @param specification - The caveat specification.\n * @returns True if the caveat specification is a restricted method caveat specification, otherwise false.\n */\nexport function isRestrictedMethodCaveatSpecification(\n  specification: CaveatSpecificationConstraint,\n): specification is RestrictedMethodCaveatSpecificationConstraint {\n  return hasProperty(specification, 'decorator');\n}\n\n/**\n * Decorate a restricted method implementation with its caveats.\n *\n * Note that all caveat functions (i.e. the argument and return value of the\n * decorator) must be awaited.\n *\n * @param methodImplementation - The restricted method implementation\n * @param permission - The origin's potential permission\n * @param caveatSpecifications - All caveat implementations\n * @returns The decorated method implementation\n */\nexport function decorateWithCaveats<\n  CaveatSpecifications extends CaveatSpecificationConstraint,\n>(\n  methodImplementation: RestrictedMethod<RestrictedMethodParameters, Json>,\n  permission: Readonly<PermissionConstraint>, // bound to the requesting origin\n  caveatSpecifications: CaveatSpecificationMap<CaveatSpecifications>, // all caveat implementations\n): RestrictedMethod<RestrictedMethodParameters, Json> {\n  const { caveats } = permission;\n  if (!caveats) {\n    return methodImplementation;\n  }\n\n  let decorated = async (\n    args: Parameters<RestrictedMethod<RestrictedMethodParameters, Json>>[0],\n  ) => methodImplementation(args);\n\n  for (const caveat of caveats) {\n    const specification =\n      caveatSpecifications[caveat.type as CaveatSpecifications['type']];\n    if (!specification) {\n      throw new UnrecognizedCaveatTypeError(caveat.type);\n    }\n\n    if (!isRestrictedMethodCaveatSpecification(specification)) {\n      throw new CaveatSpecificationMismatchError(\n        specification,\n        PermissionType.RestrictedMethod,\n      );\n    }\n    decorated = specification.decorator(decorated, caveat);\n  }\n\n  return decorated;\n}\n"]}