@metamask/permission-controller 1.0.0

package/dist/Permission.d.ts

@@ -0,0 +1,422 @@
+import { Json } from '@metamask/types';
+import { NonEmptyArray } from '@metamask/controller-utils';
+import { CaveatConstraint } from './Caveat';
+/**
+ * The origin of a subject.
+ * Effectively the GUID of an entity that can have permissions.
+ */
+export declare type OriginString = string;
+/**
+ * The name of a permission target.
+ */
+declare type TargetName = string;
+/**
+ * A `ZCAP-LD`-like permission object. A permission is associated with a
+ * particular `invoker`, which is the holder of the permission. Possessing the
+ * permission grants access to a particular restricted resource, identified by
+ * the `parentCapability`. The use of the restricted resource may be further
+ * restricted by any `caveats` associated with the permission.
+ *
+ * See the README for details.
+ */
+export declare type PermissionConstraint = {
+    /**
+     * The context(s) in which this capability is meaningful.
+     *
+     * It is required by the standard, but we make it optional since there is only
+     * one context in our usage (i.e. the user's MetaMask instance).
+     */
+    readonly '@context'?: NonEmptyArray<string>;
+    /**
+     * The caveats of the permission.
+     *
+     * @see {@link Caveat} For more information.
+     */
+    readonly caveats: null | NonEmptyArray<CaveatConstraint>;
+    /**
+     * The creation date of the permission, in UNIX epoch time.
+     */
+    readonly date: number;
+    /**
+     * The GUID of the permission object.
+     */
+    readonly id: string;
+    /**
+     * The origin string of the subject that has the permission.
+     */
+    readonly invoker: OriginString;
+    /**
+     * A pointer to the resource that possession of the capability grants
+     * access to, for example a JSON-RPC method or endowment.
+     */
+    readonly parentCapability: string;
+};
+/**
+ * A `ZCAP-LD`-like permission object. A permission is associated with a
+ * particular `invoker`, which is the holder of the permission. Possessing the
+ * permission grants access to a particular restricted resource, identified by
+ * the `parentCapability`. The use of the restricted resource may be further
+ * restricted by any `caveats` associated with the permission.
+ *
+ * See the README for details.
+ *
+ * @template TargetKey - They key of the permission target that the permission
+ * corresponds to.
+ * @template AllowedCaveat - A union of the allowed {@link Caveat} types
+ * for the permission.
+ */
+export declare type ValidPermission<TargetKey extends TargetName, AllowedCaveat extends CaveatConstraint> = PermissionConstraint & {
+    /**
+     * The caveats of the permission.
+     *
+     * @see {@link Caveat} For more information.
+     */
+    readonly caveats: AllowedCaveat extends never ? null : NonEmptyArray<AllowedCaveat> | null;
+    /**
+     * A pointer to the resource that possession of the capability grants
+     * access to, for example a JSON-RPC method or endowment.
+     */
+    readonly parentCapability: ExtractPermissionTargetNames<TargetKey>;
+};
+/**
+ * A utility type for ensuring that the given permission target name conforms to
+ * our naming conventions.
+ *
+ * See the README for the distinction between target names and keys.
+ */
+declare type ValidTargetName<Name extends string> = Name extends `${string}*` ? never : Name extends `${string}_` ? never : Name;
+/**
+ * A utility type for extracting permission target names from a union of target
+ * keys.
+ *
+ * See the README for the distinction between target names and keys.
+ *
+ * @template Key - The target key type to extract target names from.
+ */
+export declare type ExtractPermissionTargetNames<Key extends string> = ValidTargetName<Key extends `${infer Base}_*` ? `${Base}_${string}` : Key>;
+/**
+ * Extracts the permission key of a particular name from a union of keys.
+ * An internal utility type used in {@link ExtractPermissionTargetKey}.
+ *
+ * @template Key - The target key type to extract from.
+ * @template Name - The name whose key to extract.
+ */
+declare type KeyOfTargetName<Key extends string, Name extends string> = Name extends ExtractPermissionTargetNames<Key> ? Key : never;
+/**
+ * A utility type for finding the permission target key corresponding to a
+ * target name. In a way, the inverse of {@link ExtractPermissionTargetNames}.
+ *
+ * See the README for the distinction between target names and keys.
+ *
+ * @template Key - The target key type to extract from.
+ * @template Name - The name whose key to extract.
+ */
+export declare type ExtractPermissionTargetKey<Key extends string, Name extends string> = Key extends Name ? Key : Extract<Key, KeyOfTargetName<Key, Name>>;
+/**
+ * Internal utility for extracting the members types of an array. The type
+ * evalutes to `never` if the specified type is the empty tuple or neither
+ * an array nor a tuple.
+ *
+ * @template ArrayType - The array type whose members to extract.
+ */
+declare type ExtractArrayMembers<ArrayType> = ArrayType extends [] ? never : ArrayType extends any[] | readonly any[] ? ArrayType[number] : never;
+/**
+ * A utility type for extracting the allowed caveat types for a particular
+ * permission from a permission specification type.
+ *
+ * @template PermissionSpecification - The permission specification type to
+ * extract valid caveat types from.
+ */
+export declare type ExtractAllowedCaveatTypes<PermissionSpecification extends PermissionSpecificationConstraint> = ExtractArrayMembers<PermissionSpecification['allowedCaveats']>;
+/**
+ * The options object of {@link constructPermission}.
+ *
+ * @template TargetPermission - The {@link Permission} that will be constructed.
+ */
+export declare type PermissionOptions<TargetPermission extends PermissionConstraint> = {
+    target: TargetPermission['parentCapability'];
+    /**
+     * The origin string of the subject that has the permission.
+     */
+    invoker: OriginString;
+    /**
+     * The caveats of the permission.
+     * See {@link Caveat}.
+     */
+    caveats?: NonEmptyArray<CaveatConstraint>;
+};
+/**
+ * The default permission factory function. Naively constructs a permission from
+ * the inputs. Sets a default, random `id` if none is provided.
+ *
+ * @see {@link Permission} For more details.
+ * @template TargetPermission- - The {@link Permission} that will be constructed.
+ * @param options - The options for the permission.
+ * @returns The new permission object.
+ */
+export declare function constructPermission<TargetPermission extends PermissionConstraint>(options: PermissionOptions<TargetPermission>): TargetPermission;
+/**
+ * Gets the caveat of the specified type belonging to the specified permission.
+ *
+ * @param permission - The permission whose caveat to retrieve.
+ * @param caveatType - The type of the caveat to retrieve.
+ * @returns The caveat, or undefined if no such caveat exists.
+ */
+export declare function findCaveat(permission: PermissionConstraint, caveatType: string): CaveatConstraint | undefined;
+/**
+ * A requested permission object. Just an object with any of the properties
+ * of a {@link PermissionConstraint} object.
+ */
+declare type RequestedPermission = Partial<PermissionConstraint>;
+/**
+ * A record of target names and their {@link RequestedPermission} objects.
+ */
+export declare type RequestedPermissions = Record<TargetName, RequestedPermission>;
+/**
+ * The restricted method context object. Essentially a way to pass internal
+ * arguments to restricted methods and caveat functions, most importantly the
+ * requesting origin.
+ */
+declare type RestrictedMethodContext = Readonly<{
+    origin: OriginString;
+    [key: string]: any;
+}>;
+export declare type RestrictedMethodParameters = Json[] | Record<string, Json> | void;
+/**
+ * The arguments passed to a restricted method implementation.
+ *
+ * @template Params - The JSON-RPC parameters of the restricted method.
+ */
+export declare type RestrictedMethodOptions<Params extends RestrictedMethodParameters> = {
+    method: TargetName;
+    params?: Params;
+    context: RestrictedMethodContext;
+};
+/**
+ * A synchronous restricted method implementation.
+ *
+ * @template Params - The JSON-RPC parameters of the restricted method.
+ * @template Result - The JSON-RPC result of the restricted method.
+ */
+export declare type SyncRestrictedMethod<Params extends RestrictedMethodParameters, Result extends Json> = (args: RestrictedMethodOptions<Params>) => Result;
+/**
+ * An asynchronous restricted method implementation.
+ *
+ * @template Params - The JSON-RPC parameters of the restricted method.
+ * @template Result - The JSON-RPC result of the restricted method.
+ */
+export declare type AsyncRestrictedMethod<Params extends RestrictedMethodParameters, Result extends Json> = (args: RestrictedMethodOptions<Params>) => Promise<Result>;
+/**
+ * A synchronous or asynchronous restricted method implementation.
+ *
+ * @template Params - The JSON-RPC parameters of the restricted method.
+ * @template Result - The JSON-RPC result of the restricted method.
+ */
+export declare type RestrictedMethod<Params extends RestrictedMethodParameters, Result extends Json> = SyncRestrictedMethod<Params, Result> | AsyncRestrictedMethod<Params, Result>;
+export declare type ValidRestrictedMethod<MethodImplementation extends RestrictedMethod<any, any>> = MethodImplementation extends (args: infer Options) => Json | Promise<Json> ? Options extends RestrictedMethodOptions<RestrictedMethodParameters> ? MethodImplementation : never : never;
+/**
+ * {@link EndowmentGetter} parameter object.
+ */
+export declare type EndowmentGetterParams = {
+    /**
+     * The origin of the requesting subject.
+     */
+    origin: string;
+    /**
+     * Any additional data associated with the request.
+     */
+    requestData?: unknown;
+    [key: string]: unknown;
+};
+/**
+ * A synchronous or asynchronous function that gets the endowments for a
+ * particular endowment permission. The getter receives the origin of the
+ * requesting subject and, optionally, additional request metadata.
+ */
+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;
+/**
+ * A utility type for ensuring that the given permission target key conforms to
+ * our naming conventions.
+ *
+ * See the README for the distinction between target names and keys.
+ *
+ * @template Key - The target key string to apply the constraint to.
+ */
+declare type ValidTargetKey<Key extends string> = Key extends `${string}_*` ? Key : Key extends `${string}_` ? never : Key extends `${string}*` ? never : Key;
+/**
+ * The different possible types of permissions.
+ */
+export declare enum PermissionType {
+    /**
+     * A restricted JSON-RPC method. A subject must have the requisite permission
+     * to call a restricted JSON-RPC method.
+     */
+    RestrictedMethod = "RestrictedMethod",
+    /**
+     * An "endowment" granted to subjects that possess the requisite permission,
+     * such as a global environment variable exposing a restricted API, etc.
+     */
+    Endowment = "Endowment"
+}
+/**
+ * The base constraint for permission specification objects. Every
+ * {@link Permission} supported by a {@link PermissionController} must have an
+ * associated specification, which is the source of truth for all permission-
+ * related types. A permission specification includes the list of permitted
+ * caveats, and any factory and validation functions specified by the consumer.
+ * A concrete permission specification may specify further fields as necessary.
+ *
+ * See the README for more details.
+ */
+declare type PermissionSpecificationBase<Type extends PermissionType> = {
+    /**
+     * The type of the specified permission.
+     */
+    permissionType: Type;
+    /**
+     * The target resource of the permission. The shape of this string depends on
+     * the permission type. For example, a restricted method target key will
+     * consist of either a complete method name or the prefix of a namespaced
+     * method, e.g. `wallet_snap_*`.
+     */
+    targetKey: string;
+    /**
+     * An array of the caveat types that may be added to instances of this
+     * permission.
+     */
+    allowedCaveats: Readonly<NonEmptyArray<string>> | null;
+    /**
+     * The factory function used to get permission objects. Permissions returned
+     * by this function are presumed to valid, and they will not be passed to the
+     * validator function associated with this specification (if any). In other
+     * words, the factory function should validate the permissions it creates.
+     *
+     * If no factory is specified, the {@link Permission} constructor will be
+     * used, and the validator function (if specified) will be called on newly
+     * constructed permissions.
+     */
+    factory?: PermissionFactory<any, Record<string, unknown>>;
+    /**
+     * The validator function used to validate permissions of the associated type
+     * whenever they are mutated. The only way a permission can be legally mutated
+     * is when its caveats are modified by the permission controller.
+     *
+     * The validator should throw an appropriate JSON-RPC error if validation fails.
+     */
+    validator?: PermissionValidatorConstraint;
+};
+/**
+ * The constraint for restricted method permission specification objects.
+ * Permissions that correspond to JSON-RPC methods are specified using objects
+ * that conform to this type.
+ *
+ * See the README for more details.
+ */
+export declare type RestrictedMethodSpecificationConstraint = PermissionSpecificationBase<PermissionType.RestrictedMethod> & {
+    /**
+     * The implementation of the restricted method that the permission
+     * corresponds to.
+     */
+    methodImplementation: RestrictedMethod<any, any>;
+};
+/**
+ * The constraint for endowment permission specification objects. Permissions
+ * that endow callers with some restricted resource are specified using objects
+ * that conform to this type.
+ *
+ * See the README for more details.
+ */
+export declare type EndowmentSpecificationConstraint = PermissionSpecificationBase<PermissionType.Endowment> & {
+    /**
+     * The {@link EndowmentGetter} function for the permission. This function
+     * will be called by the {@link PermissionController} whenever the
+     * permission is invoked, after which the host can apply the endowments to
+     * the requesting subject in the intended manner.
+     */
+    endowmentGetter: EndowmentGetter<any>;
+};
+/**
+ * The constraint for permission specification objects. Every {@link Permission}
+ * supported by a {@link PermissionController} must have an associated
+ * specification, which is the source of truth for all permission-related types.
+ * All specifications must adhere to the {@link PermissionSpecificationBase}
+ * interface, but specifications may have different fields depending on the
+ * {@link PermissionType}.
+ *
+ * See the README for more details.
+ */
+export declare type PermissionSpecificationConstraint = EndowmentSpecificationConstraint | RestrictedMethodSpecificationConstraint;
+/**
+ * Options for {@link PermissionSpecificationBuilder} functions.
+ */
+declare type PermissionSpecificationBuilderOptions<FactoryHooks extends Record<string, unknown>, MethodHooks extends Record<string, unknown>, ValidatorHooks extends Record<string, unknown>> = {
+    targetKey?: string;
+    allowedCaveats?: Readonly<NonEmptyArray<string>> | null;
+    factoryHooks?: FactoryHooks;
+    methodHooks?: MethodHooks;
+    validatorHooks?: ValidatorHooks;
+};
+/**
+ * A function that builds a permission specification. Modules that specify
+ * permissions 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 PermissionSpecificationBuilder<Type extends PermissionType, Options extends PermissionSpecificationBuilderOptions<any, any, any>, Specification extends PermissionSpecificationConstraint & {
+    permissionType: Type;
+}> = (options: Options) => Specification;
+/**
+ * A restricted method permission export object, containing the
+ * {@link PermissionSpecificationBuilder} function and "hook name" objects.
+ */
+export declare type PermissionSpecificationBuilderExportConstraint = {
+    targetKey: string;
+    specificationBuilder: PermissionSpecificationBuilder<PermissionType, PermissionSpecificationBuilderOptions<any, any, any>, PermissionSpecificationConstraint>;
+    factoryHookNames?: Record<string, true>;
+    methodHookNames?: Record<string, true>;
+    validatorHookNames?: Record<string, true>;
+};
+declare type ValidRestrictedMethodSpecification<Specification extends RestrictedMethodSpecificationConstraint> = Specification['methodImplementation'] extends ValidRestrictedMethod<Specification['methodImplementation']> ? Specification : never;
+/**
+ * Constraint for {@link PermissionSpecificationConstraint} objects that
+ * evaluates to `never` if the specification contains any invalid fields.
+ *
+ * @template Specification - The permission specification to validate.
+ */
+export declare type ValidPermissionSpecification<Specification extends PermissionSpecificationConstraint> = Specification['targetKey'] extends ValidTargetKey<Specification['targetKey']> ? Specification['permissionType'] extends PermissionType.Endowment ? Specification : Specification['permissionType'] extends PermissionType.RestrictedMethod ? ValidRestrictedMethodSpecification<Extract<Specification, RestrictedMethodSpecificationConstraint>> : never : never;
+/**
+ * Checks that the specification has the expected permission type.
+ *
+ * @param specification - The specification to check.
+ * @param expectedType - The expected permission type.
+ * @template Specification - The specification to check.
+ * @template Type - The expected permission type.
+ * @returns Whether or not the specification is of the expected type.
+ */
+export declare function hasSpecificationType<Specification extends PermissionSpecificationConstraint, Type extends PermissionType>(specification: Specification, expectedType: Type): specification is Specification & {
+    permissionType: Type;
+};
+/**
+ * The specifications for all permissions supported by a particular
+ * {@link PermissionController}.
+ *
+ * @template Specifications - The union of all {@link PermissionSpecificationConstraint} types.
+ */
+export declare type PermissionSpecificationMap<Specification extends PermissionSpecificationConstraint> = {
+    [TargetKey in Specification['targetKey']]: Specification extends {
+        targetKey: TargetKey;
+    } ? Specification : never;
+};
+/**
+ * Extracts a specific {@link PermissionSpecificationConstraint} from a union of
+ * permission specifications.
+ *
+ * @template Specification - The specification union type to extract from.
+ * @template TargetKey - The `targetKey` of the specification to extract.
+ */
+export declare type ExtractPermissionSpecification<Specification extends PermissionSpecificationConstraint, TargetKey extends Specification['targetKey']> = Specification extends {
+    targetKey: TargetKey;
+} ? Specification : never;
+export {};

package/dist/Permission.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasSpecificationType = exports.PermissionType = exports.findCaveat = exports.constructPermission = void 0;
+const nanoid_1 = require("nanoid");
+/**
+ * The default permission factory function. Naively constructs a permission from
+ * the inputs. Sets a default, random `id` if none is provided.
+ *
+ * @see {@link Permission} For more details.
+ * @template TargetPermission- - The {@link Permission} that will be constructed.
+ * @param options - The options for the permission.
+ * @returns The new permission object.
+ */
+function constructPermission(options) {
+    const { caveats = null, invoker, target } = options;
+    return {
+        id: (0, nanoid_1.nanoid)(),
+        parentCapability: target,
+        invoker,
+        caveats,
+        date: new Date().getTime(),
+    };
+}
+exports.constructPermission = constructPermission;
+/**
+ * Gets the caveat of the specified type belonging to the specified permission.
+ *
+ * @param permission - The permission whose caveat to retrieve.
+ * @param caveatType - The type of the caveat to retrieve.
+ * @returns The caveat, or undefined if no such caveat exists.
+ */
+function findCaveat(permission, caveatType) {
+    var _a;
+    return (_a = permission.caveats) === null || _a === void 0 ? void 0 : _a.find((caveat) => caveat.type === caveatType);
+}
+exports.findCaveat = findCaveat;
+/**
+ * The different possible types of permissions.
+ */
+var PermissionType;
+(function (PermissionType) {
+    /**
+     * A restricted JSON-RPC method. A subject must have the requisite permission
+     * to call a restricted JSON-RPC method.
+     */
+    PermissionType["RestrictedMethod"] = "RestrictedMethod";
+    /**
+     * An "endowment" granted to subjects that possess the requisite permission,
+     * such as a global environment variable exposing a restricted API, etc.
+     */
+    PermissionType["Endowment"] = "Endowment";
+})(PermissionType = exports.PermissionType || (exports.PermissionType = {}));
+/**
+ * Checks that the specification has the expected permission type.
+ *
+ * @param specification - The specification to check.
+ * @param expectedType - The expected permission type.
+ * @template Specification - The specification to check.
+ * @template Type - The expected permission type.
+ * @returns Whether or not the specification is of the expected type.
+ */
+function hasSpecificationType(specification, expectedType) {
+    return specification.permissionType === expectedType;
+}
+exports.hasSpecificationType = hasSpecificationType;
+//# sourceMappingURL=Permission.js.map

package/dist/Permission.js.map

@@ -0,0 +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"]}