import type { ApprovalControllerAcceptRequestAction, ApprovalControllerAddRequestAction, ApprovalControllerHasRequestAction, ApprovalControllerRejectRequestAction } from "@metamask/approval-controller";
import type { ControllerGetStateAction, ControllerStateChangeEvent } from "@metamask/base-controller";
import { BaseController } from "@metamask/base-controller";
import type { NonEmptyArray } from "@metamask/controller-utils";
import type { Messenger, ActionConstraint, EventConstraint } from "@metamask/messenger";
import type { Json } from "@metamask/utils";
import type { CaveatConstraint, CaveatDiffMap, CaveatSpecificationConstraint, CaveatSpecificationMap, ExtractCaveat, ExtractCaveats, ExtractCaveatValue } from "./Caveat.cjs";
import type { EndowmentSpecificationConstraint, ExtractAllowedCaveatTypes, OriginString, PermissionConstraint, PermissionSpecificationConstraint, PermissionSpecificationMap, RequestedPermissions, RestrictedMethodParameters, RestrictedMethodSpecificationConstraint, SideEffectHandler, ValidPermission, ValidPermissionSpecification } from "./Permission.cjs";
import type { PermissionControllerMethodActions } from "./PermissionController-method-action-types.cjs";
import type { SubjectMetadataControllerGetSubjectMetadataAction } from "./SubjectMetadataController-method-action-types.cjs";
/**
 * Metadata associated with {@link PermissionController} subjects.
 */
export type PermissionSubjectMetadata = {
    origin: OriginString;
};
/**
 * Metadata associated with permission requests.
 */
export type PermissionsRequestMetadata = PermissionSubjectMetadata & {
    id: string;
    [key: string]: Json;
};
/**
 * A diff produced by an incremental permissions request.
 */
export type PermissionDiffMap<TargetName extends string, AllowedCaveats extends CaveatConstraint> = Record<TargetName, CaveatDiffMap<AllowedCaveats>>;
/**
 * Used for prompting the user about a proposed new permission.
 * Includes information about the grantee subject, requested permissions, the
 * diff relative to the previously granted permissions (if relevant), and any
 * additional information added by the consumer.
 *
 * All properties except `diff` and `permissions` are passed to any factories
 * for the requested permissions.
 */
export type PermissionsRequest = {
    metadata: PermissionsRequestMetadata;
    permissions: RequestedPermissions;
    [key: string]: Json;
} & {
    diff?: {
        currentPermissions: SubjectPermissions<PermissionConstraint>;
        permissionDiffMap: PermissionDiffMap<string, CaveatConstraint>;
    };
};
/**
 * Metadata associated with an approved permission request.
 */
type ApprovedPermissionsMetadata = {
    data?: Record<string, unknown>;
    id: string;
    origin: OriginString;
};
export type SideEffects = {
    permittedHandlers: Record<string, SideEffectHandler<ActionConstraint, EventConstraint>>;
    failureHandlers: Record<string, SideEffectHandler<ActionConstraint, EventConstraint>>;
};
/**
 * The name of the {@link PermissionController}.
 */
declare const controllerName = "PermissionController";
/**
 * Permissions associated with a {@link PermissionController} subject.
 */
export type SubjectPermissions<Permission extends PermissionConstraint> = Record<Permission['parentCapability'], Permission>;
/**
 * Permissions and metadata associated with a {@link PermissionController}
 * subject.
 */
export type PermissionSubjectEntry<SubjectPermission extends PermissionConstraint> = {
    origin: SubjectPermission['invoker'];
    permissions: SubjectPermissions<SubjectPermission>;
};
/**
 * All subjects of a {@link PermissionController}.
 *
 * @template SubjectPermission - The permissions of the subject.
 */
export type PermissionControllerSubjects<SubjectPermission extends PermissionConstraint> = Record<SubjectPermission['invoker'], PermissionSubjectEntry<SubjectPermission>>;
/**
 * The state of a {@link PermissionController}.
 *
 * @template Permission - The controller's permission type union.
 */
export type PermissionControllerState<Permission> = Permission extends PermissionConstraint ? {
    subjects: PermissionControllerSubjects<Permission>;
} : never;
/**
 * Gets the state of the {@link PermissionController}.
 */
export type PermissionControllerGetStateAction = ControllerGetStateAction<typeof controllerName, PermissionControllerState<PermissionConstraint>>;
/**
 * Gets the state of the {@link PermissionController}.
 *
 * @deprecated Use `PermissionControllerGetStateAction` instead.
 */
export type GetPermissionControllerState = PermissionControllerGetStateAction;
/**
 * Gets the names of all subjects from the {@link PermissionController}.
 *
 * @deprecated Use `PermissionControllerGetSubjectNamesAction` instead.
 */
export type GetSubjects = {
    type: `${typeof controllerName}:getSubjectNames`;
    handler: () => (keyof PermissionControllerSubjects<PermissionConstraint>)[];
};
/**
 * Gets the permissions for specified subject.
 *
 * @deprecated Use `PermissionControllerGetPermissionsAction` instead.
 */
export type GetPermissions = {
    type: `${typeof controllerName}:getPermissions`;
    handler: GenericPermissionController['getPermissions'];
};
/**
 * Checks whether the specified subject has any permissions.
 *
 * @deprecated Use `PermissionControllerHasPermissionAction` instead.
 */
export type HasPermissions = {
    type: `${typeof controllerName}:hasPermissions`;
    handler: GenericPermissionController['hasPermissions'];
};
/**
 * Checks whether the specified subject has a specific permission.
 *
 * @deprecated Use `PermissionControllerHasPermissionAction` instead.
 */
export type HasPermission = {
    type: `${typeof controllerName}:hasPermission`;
    handler: GenericPermissionController['hasPermission'];
};
/**
 * Directly grants given permissions for a specified origin without requesting user approval.
 *
 * @deprecated Use `PermissionControllerGrantPermissionsAction` instead.
 */
export type GrantPermissions = {
    type: `${typeof controllerName}:grantPermissions`;
    handler: GenericPermissionController['grantPermissions'];
};
/**
 * Directly grants given permissions for a specified origin without requesting user approval.
 *
 * @deprecated Use `PermissionControllerGrantPermissionsIncrementalAction`
 * instead.
 */
export type GrantPermissionsIncremental = {
    type: `${typeof controllerName}:grantPermissionsIncremental`;
    handler: GenericPermissionController['grantPermissionsIncremental'];
};
/**
 * Requests given permissions for a specified origin.
 *
 * @deprecated Use `PermissionControllerRequestPermissionsAction` instead.
 */
export type RequestPermissions = {
    type: `${typeof controllerName}:requestPermissions`;
    handler: GenericPermissionController['requestPermissions'];
};
/**
 * Requests given permissions for a specified origin.
 *
 * @deprecated Use `PermissionControllerRequestPermissionsAction` instead.
 */
export type RequestPermissionsIncremental = {
    type: `${typeof controllerName}:requestPermissionsIncremental`;
    handler: GenericPermissionController['requestPermissionsIncremental'];
};
/**
 * Removes the specified permissions for each origin.
 *
 * @deprecated Use `PermissionControllerRevokePermissionsAction` instead.
 */
export type RevokePermissions = {
    type: `${typeof controllerName}:revokePermissions`;
    handler: GenericPermissionController['revokePermissions'];
};
/**
 * Removes all permissions for a given origin.
 *
 * @deprecated Use `PermissionControllerRevokeAllPermissionAction` instead.
 */
export type RevokeAllPermissions = {
    type: `${typeof controllerName}:revokeAllPermissions`;
    handler: GenericPermissionController['revokeAllPermissions'];
};
/**
 * Revokes all permissions corresponding to the specified target for all subjects.
 * Does nothing if no subjects or no such permission exists.
 *
 * @deprecated Use `PermissionControllerRevokePermissionForAllSubjectsAction`
 * instead.
 */
export type RevokePermissionForAllSubjects = {
    type: `${typeof controllerName}:revokePermissionForAllSubjects`;
    handler: GenericPermissionController['revokePermissionForAllSubjects'];
};
/**
 * Updates a caveat value for a specified caveat type belonging to a specific target and origin.
 *
 * @deprecated Use `PermissionControllerUpdateCaveatAction` instead.
 */
export type UpdateCaveat = {
    type: `${typeof controllerName}:updateCaveat`;
    handler: GenericPermissionController['updateCaveat'];
};
/**
 * Get a caveat value for a specified caveat type belonging to a specific target and origin.
 *
 * @deprecated Use `PermissionControllerGetCaveatAction` instead.
 */
export type GetCaveat = {
    type: `${typeof controllerName}:getCaveat`;
    handler: GenericPermissionController['getCaveat'];
};
/**
 * Clears all permissions from the {@link PermissionController}.
 *
 * @deprecated Use `PermissionControllerClearStateAction` instead.
 */
export type ClearPermissions = {
    type: `${typeof controllerName}:clearPermissions`;
    handler: () => void;
};
/**
 * Gets the endowments for the given subject and permission.
 *
 * @deprecated Use `PermissionControllerGetEndowmentsAction` instead.
 */
export type GetEndowments = {
    type: `${typeof controllerName}:getEndowments`;
    handler: GenericPermissionController['getEndowments'];
};
/**
 * The {@link Messenger} actions of the {@link PermissionController}.
 */
export type PermissionControllerActions = PermissionControllerGetStateAction | PermissionControllerMethodActions;
/**
 * The generic state change event of the {@link PermissionController}.
 */
export type PermissionControllerStateChange = ControllerStateChangeEvent<typeof controllerName, PermissionControllerState<PermissionConstraint>>;
/**
 * The {@link Messenger} events of the {@link PermissionController}.
 *
 * The permission controller only emits its generic state change events.
 * Consumers should use selector subscriptions to subscribe to relevant
 * substate.
 */
export type PermissionControllerEvents = PermissionControllerStateChange;
/**
 * The external {@link Messenger} actions available to the
 * {@link PermissionController}.
 */
type AllowedActions = ApprovalControllerAddRequestAction | ApprovalControllerHasRequestAction | ApprovalControllerAcceptRequestAction | ApprovalControllerRejectRequestAction | SubjectMetadataControllerGetSubjectMetadataAction;
/**
 * The messenger of the {@link PermissionController}.
 */
export type PermissionControllerMessenger = Messenger<typeof controllerName, PermissionControllerActions | AllowedActions, PermissionControllerEvents>;
export type SideEffectMessenger<Actions extends ActionConstraint, Events extends EventConstraint> = Messenger<typeof controllerName, Actions | AllowedActions, Events>;
/**
 * A generic {@link PermissionController}.
 */
export type GenericPermissionController = PermissionController<PermissionSpecificationConstraint, CaveatSpecificationConstraint>;
/**
 * Describes the possible results of a {@link CaveatMutator} function.
 */
export declare enum CaveatMutatorOperation {
    Noop = 0,
    UpdateValue = 1,
    DeleteCaveat = 2,
    RevokePermission = 3
}
/**
 * Given a caveat value, returns a {@link CaveatMutatorOperation} and, optionally,
 * a new caveat value.
 *
 * @see {@link PermissionController.updatePermissionsByCaveat} for more details.
 * @template Caveat - The caveat type for which this mutator is intended.
 * @param caveatValue - The existing value of the caveat being mutated.
 * @returns A tuple of the mutation result and, optionally, the new caveat
 * value.
 */
export type CaveatMutator<TargetCaveat extends CaveatConstraint> = (caveatValue: TargetCaveat['value']) => CaveatMutatorResult;
type CaveatMutatorResult = Readonly<{
    operation: CaveatMutatorOperation.UpdateValue;
    value: CaveatConstraint['value'];
}> | Readonly<{
    operation: Exclude<CaveatMutatorOperation, CaveatMutatorOperation.UpdateValue>;
}>;
/**
 * Extracts the permission(s) specified by the given permission and caveat
 * specifications.
 *
 * @template ControllerPermissionSpecification - The permission specification(s)
 * to extract from.
 * @template ControllerCaveatSpecification - The caveat specification(s) to
 * extract from. Necessary because {@link Permission} has a generic parameter
 * that describes the allowed caveats for the permission.
 */
export type ExtractPermission<ControllerPermissionSpecification extends PermissionSpecificationConstraint, ControllerCaveatSpecification extends CaveatSpecificationConstraint> = ControllerPermissionSpecification extends ValidPermissionSpecification<ControllerPermissionSpecification> ? ValidPermission<ControllerPermissionSpecification['targetName'], ExtractCaveats<ControllerCaveatSpecification>> : never;
/**
 * Extracts the restricted method permission(s) specified by the given
 * permission and caveat specifications.
 *
 * @template ControllerPermissionSpecification - The permission specification(s)
 * to extract from.
 * @template ControllerCaveatSpecification - The caveat specification(s) to
 * extract from. Necessary because {@link Permission} has a generic parameter
 * that describes the allowed caveats for the permission.
 */
export type ExtractRestrictedMethodPermission<ControllerPermissionSpecification extends PermissionSpecificationConstraint, ControllerCaveatSpecification extends CaveatSpecificationConstraint> = ExtractPermission<Extract<ControllerPermissionSpecification, RestrictedMethodSpecificationConstraint>, ControllerCaveatSpecification>;
/**
 * Extracts the endowment permission(s) specified by the given permission and
 * caveat specifications.
 *
 * @template ControllerPermissionSpecification - The permission specification(s)
 * to extract from.
 * @template ControllerCaveatSpecification - The caveat specification(s) to
 * extract from. Necessary because {@link Permission} has a generic parameter
 * that describes the allowed caveats for the permission.
 */
export type ExtractEndowmentPermission<ControllerPermissionSpecification extends PermissionSpecificationConstraint, ControllerCaveatSpecification extends CaveatSpecificationConstraint> = ExtractPermission<Extract<ControllerPermissionSpecification, EndowmentSpecificationConstraint>, ControllerCaveatSpecification>;
/**
 * Options for the {@link PermissionController} constructor.
 *
 * @template ControllerPermissionSpecification - A union of the types of all
 * permission specifications available to the controller. Any referenced caveats
 * must be included in the controller's caveat specifications.
 * @template ControllerCaveatSpecification - A union of the types of all
 * caveat specifications available to the controller.
 */
export type PermissionControllerOptions<ControllerPermissionSpecification extends PermissionSpecificationConstraint, ControllerCaveatSpecification extends CaveatSpecificationConstraint> = {
    messenger: PermissionControllerMessenger;
    caveatSpecifications: CaveatSpecificationMap<ControllerCaveatSpecification>;
    permissionSpecifications: PermissionSpecificationMap<ControllerPermissionSpecification>;
    unrestrictedMethods: readonly string[];
    state?: Partial<PermissionControllerState<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>>;
};
/**
 * The permission controller. See the [Architecture](../ARCHITECTURE.md)
 * document for details.
 *
 * Assumes the existence of an {@link ApprovalController} reachable via the
 * {@link Messenger}.
 *
 * @template ControllerPermissionSpecification - A union of the types of all
 * permission specifications available to the controller. Any referenced caveats
 * must be included in the controller's caveat specifications.
 * @template ControllerCaveatSpecification - A union of the types of all
 * caveat specifications available to the controller.
 */
export declare class PermissionController<ControllerPermissionSpecification extends PermissionSpecificationConstraint = PermissionSpecificationConstraint, ControllerCaveatSpecification extends CaveatSpecificationConstraint = CaveatSpecificationConstraint> extends BaseController<typeof controllerName, PermissionControllerState<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>, PermissionControllerMessenger> {
    #private;
    /**
     * The names of all JSON-RPC methods that will be ignored by the controller.
     *
     * @returns The names of all unrestricted JSON-RPC methods
     */
    get unrestrictedMethods(): ReadonlySet<string>;
    /**
     * Checks whether the given method was declared as unrestricted at
     * construction time. Methods unknown to the controller return `false` and
     * would be treated as restricted by callers such as the permission
     * middleware.
     *
     * @param method - The name of the method to check.
     * @returns Whether the method is unrestricted.
     */
    hasUnrestrictedMethod(method: string): boolean;
    /**
     * Constructs the PermissionController.
     *
     * @param options - Permission controller options.
     * @param options.caveatSpecifications - The specifications of all caveats
     * available to the controller. See {@link CaveatSpecificationMap} and the
     * documentation for more details.
     * @param options.permissionSpecifications - The specifications of all
     * permissions available to the controller. See
     * {@link PermissionSpecificationMap} and the README for more details.
     * @param options.unrestrictedMethods - The callable names of all JSON-RPC
     * methods ignored by the new controller.
     * @param options.messenger - The messenger. See
     * {@link BaseController} for more information.
     * @param options.state - Existing state to hydrate the controller with at
     * initialization.
     */
    constructor(options: PermissionControllerOptions<ControllerPermissionSpecification, ControllerCaveatSpecification>);
    /**
     * Clears the state of the controller.
     */
    clearState(): void;
    /**
     * Gets a list of all origins of subjects.
     *
     * @returns The origins (i.e. IDs) of all subjects.
     */
    getSubjectNames(): OriginString[];
    /**
     * Gets the permission for the specified target of the subject corresponding
     * to the specified origin.
     *
     * @param origin - The origin of the subject.
     * @param targetName - The method name as invoked by a third party (i.e., not
     * a method key).
     * @returns The permission if it exists, or undefined otherwise.
     */
    getPermission<SubjectPermission extends ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>(origin: OriginString, targetName: SubjectPermission['parentCapability']): SubjectPermission | undefined;
    /**
     * Gets all permissions for the specified subject, if any.
     *
     * @param origin - The origin of the subject.
     * @returns The permissions of the subject, if any.
     */
    getPermissions(origin: OriginString): SubjectPermissions<ValidPermission<string, ExtractCaveats<ControllerCaveatSpecification>>> | undefined;
    /**
     * Checks whether the subject with the specified origin has the specified
     * permission.
     *
     * @param origin - The origin of the subject.
     * @param target - The target name of the permission.
     * @returns Whether the subject has the permission.
     */
    hasPermission(origin: OriginString, target: ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability']): boolean;
    /**
     * Checks whether the subject with the specified origin has any permissions.
     * Use this if you want to know if a subject "exists".
     *
     * @param origin - The origin of the subject to check.
     * @returns Whether the subject has any permissions.
     */
    hasPermissions(origin: OriginString): boolean;
    /**
     * Revokes all permissions from the specified origin.
     *
     * Throws an error if the origin has no permissions.
     *
     * @param origin - The origin whose permissions to revoke.
     */
    revokeAllPermissions(origin: OriginString): void;
    /**
     * Revokes the specified permission from the subject with the specified
     * origin.
     *
     * Throws an error if the subject or the permission does not exist.
     *
     * @param origin - The origin of the subject whose permission to revoke.
     * @param target - The target name of the permission to revoke.
     */
    revokePermission(origin: OriginString, target: ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability']): void;
    /**
     * Revokes the specified permissions from the specified subjects.
     *
     * Throws an error if any of the subjects or permissions do not exist.
     *
     * @param subjectsAndPermissions - An object mapping subject origins
     * to arrays of permission target names to revoke.
     */
    revokePermissions(subjectsAndPermissions: Record<OriginString, NonEmptyArray<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability']>>): void;
    /**
     * Revokes all permissions corresponding to the specified target for all subjects.
     * Does nothing if no subjects or no such permission exists.
     *
     * @param target - The name of the target to revoke all permissions for.
     */
    revokePermissionForAllSubjects(target: ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability']): void;
    /**
     * Checks whether the permission of the subject corresponding to the given
     * origin has a caveat of the specified type.
     *
     * Throws an error if the subject does not have a permission with the
     * specified target name.
     *
     * @template TargetName - The permission target name. Should be inferred.
     * @template CaveatType - The valid caveat types for the permission. Should
     * be inferred.
     * @param origin - The origin of the subject.
     * @param target - The target name of the permission.
     * @param caveatType - The type of the caveat to check for.
     * @returns Whether the permission has the specified caveat.
     */
    hasCaveat<TargetName extends ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability'], CaveatType extends ExtractAllowedCaveatTypes<ControllerPermissionSpecification>>(origin: OriginString, target: TargetName, caveatType: CaveatType): boolean;
    /**
     * Gets the caveat of the specified type, if any, for the permission of
     * the subject corresponding to the given origin.
     *
     * Throws an error if the subject does not have a permission with the
     * specified target name.
     *
     * @template TargetName - The permission target name. Should be inferred.
     * @template CaveatType - The valid caveat types for the permission. Should
     * be inferred.
     * @param origin - The origin of the subject.
     * @param target - The target name of the permission.
     * @param caveatType - The type of the caveat to get.
     * @returns The caveat, or `undefined` if no such caveat exists.
     */
    getCaveat<TargetName extends ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability'], CaveatType extends ExtractAllowedCaveatTypes<ControllerPermissionSpecification>>(origin: OriginString, target: TargetName, caveatType: CaveatType): ExtractCaveat<ControllerCaveatSpecification, CaveatType> | undefined;
    /**
     * Adds a caveat of the specified type, with the specified caveat value, to
     * the permission corresponding to the given subject origin and permission
     * target.
     *
     * For modifying existing caveats, use
     * {@link PermissionController.updateCaveat}.
     *
     * Throws an error if no such permission exists, or if the caveat already
     * exists.
     *
     * @template TargetName - The permission target name. Should be inferred.
     * @template CaveatType - The valid caveat types for the permission. Should
     * be inferred.
     * @param origin - The origin of the subject.
     * @param target - The target name of the permission.
     * @param caveatType - The type of the caveat to add.
     * @param caveatValue - The value of the caveat to add.
     */
    addCaveat<TargetName extends ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability'], CaveatType extends ExtractAllowedCaveatTypes<ControllerPermissionSpecification>>(origin: OriginString, target: TargetName, caveatType: CaveatType, caveatValue: ExtractCaveatValue<ControllerCaveatSpecification, CaveatType>): void;
    /**
     * Updates the value of the caveat of the specified type belonging to the
     * permission corresponding to the given subject origin and permission
     * target.
     *
     * For adding new caveats, use
     * {@link PermissionController.addCaveat}.
     *
     * Throws an error if no such permission or caveat exists.
     *
     * @template TargetName - The permission target name. Should be inferred.
     * @template CaveatType - The valid caveat types for the permission. Should
     * be inferred.
     * @param origin - The origin of the subject.
     * @param target - The target name of the permission.
     * @param caveatType - The type of the caveat to update.
     * @param caveatValue - The new value of the caveat.
     */
    updateCaveat<TargetName extends ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability'], CaveatType extends ExtractAllowedCaveatTypes<ControllerPermissionSpecification>, CaveatValue extends ExtractCaveatValue<ControllerCaveatSpecification, CaveatType>>(origin: OriginString, target: TargetName, caveatType: CaveatType, caveatValue: CaveatValue): void;
    /**
     * Updates all caveats with the specified type for all subjects and
     * permissions by applying the specified mutator function to them.
     *
     * ATTN: Permissions can be revoked entirely by the action of this method,
     * read on for details.
     *
     * Caveat mutators are functions that receive a caveat value and return a
     * tuple consisting of a {@link CaveatMutatorOperation} and, optionally, a new
     * value to update the existing caveat with.
     *
     * For each caveat, depending on the mutator result, this method will:
     * - Do nothing ({@link CaveatMutatorOperation.Noop})
     * - Update the value of the caveat ({@link CaveatMutatorOperation.UpdateValue}). The caveat specification validator, if any, will be called after updating the value.
     * - Delete the caveat ({@link CaveatMutatorOperation.DeleteCaveat}). The permission specification validator, if any, will be called after deleting the caveat.
     * - Revoke the parent permission ({@link CaveatMutatorOperation.RevokePermission})
     *
     * This method throws if the validation of any caveat or permission fails.
     *
     * @param targetCaveatType - The type of the caveats to update.
     * @param mutator - The mutator function which will be applied to all caveat
     * values.
     */
    updatePermissionsByCaveat<CaveatType extends ExtractCaveats<ControllerCaveatSpecification>['type'], TargetCaveat extends ExtractCaveat<ControllerCaveatSpecification, CaveatType>>(targetCaveatType: CaveatType, mutator: CaveatMutator<TargetCaveat>): void;
    /**
     * Removes the caveat of the specified type from the permission corresponding
     * to the given subject origin and target name.
     *
     * Throws an error if no such permission or caveat exists.
     *
     * @template TargetName - The permission target name. Should be inferred.
     * @template CaveatType - The valid caveat types for the permission. Should
     * be inferred.
     * @param origin - The origin of the subject.
     * @param target - The target name of the permission.
     * @param caveatType - The type of the caveat to remove.
     */
    removeCaveat<TargetName extends ControllerPermissionSpecification['targetName'], CaveatType extends ExtractAllowedCaveatTypes<ControllerPermissionSpecification>>(origin: OriginString, target: TargetName, caveatType: CaveatType): void;
    /**
     * Grants _approved_ permissions to the specified subject. Every permission and
     * caveat is stringently validated—including by calling their specification
     * validators—and an error is thrown if validation fails.
     *
     * ATTN: This method does **not** prompt the user for approval. User consent must
     * first be obtained through some other means.
     *
     * @see {@link PermissionController.requestPermissions} For initiating a
     * permissions request requiring user approval.
     * @param options - Options bag.
     * @param options.approvedPermissions - The requested permissions approved by
     * the user.
     * @param options.requestData - Permission request data. Passed to permission
     * factory functions.
     * @param options.preserveExistingPermissions - Whether to preserve the
     * subject's existing permissions.
     * @param options.subject - The subject to grant permissions to.
     * @returns The subject's new permission state. It may or may not have changed.
     */
    grantPermissions({ approvedPermissions, requestData, preserveExistingPermissions, subject, }: {
        approvedPermissions: RequestedPermissions;
        subject: PermissionSubjectMetadata;
        preserveExistingPermissions?: boolean;
        requestData?: Record<string, unknown>;
    }): Partial<SubjectPermissions<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>>;
    /**
     * Incrementally grants _approved_ permissions to the specified subject. Every
     * permission and caveat is stringently validated—including by calling their
     * specification validators—and an error is thrown if validation fails.
     *
     * ATTN: This method does **not** prompt the user for approval. User consent must
     * first be obtained through some other means.
     *
     * @see {@link PermissionController.requestPermissionsIncremental} For initiating
     * an incremental permissions request requiring user approval.
     * @param options - Options bag.
     * @param options.approvedPermissions - The requested permissions approved by
     * the user.
     * @param options.requestData - Permission request data. Passed to permission
     * factory functions.
     * @param options.subject - The subject to grant permissions to.
     * @returns The subject's new permission state. It may or may not have changed.
     */
    grantPermissionsIncremental({ approvedPermissions, requestData, subject, }: {
        approvedPermissions: RequestedPermissions;
        subject: PermissionSubjectMetadata;
        requestData?: Record<string, unknown>;
    }): Partial<SubjectPermissions<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>>;
    /**
     * Initiates a permission request that requires user approval.
     *
     * Either this or {@link PermissionController.requestPermissionsIncremental}
     * should always be used to grant additional permissions to a subject,
     * unless user approval has been obtained through some other means.
     *
     * Permissions are validated at every step of the approval process, and this
     * method will reject if validation fails.
     *
     * @see {@link ApprovalController} For the user approval logic.
     * @see {@link PermissionController.acceptPermissionsRequest} For the method
     * that _accepts_ the request and resolves the user approval promise.
     * @see {@link PermissionController.rejectPermissionsRequest} For the method
     * that _rejects_ the request and the user approval promise.
     * @param subject - The grantee subject.
     * @param requestedPermissions - The requested permissions.
     * @param options - Additional options.
     * @param options.id - The id of the permissions request. Defaults to a unique
     * id.
     * @param options.preserveExistingPermissions - Whether to preserve the
     * subject's existing permissions. Defaults to `true`.
     * @param options.metadata - Additional metadata about the permission request.
     * @returns The granted permissions and request metadata.
     */
    requestPermissions(subject: PermissionSubjectMetadata, requestedPermissions: RequestedPermissions, options?: {
        id?: string;
        preserveExistingPermissions?: boolean;
        metadata?: Record<string, Json>;
    }): Promise<[
        Partial<SubjectPermissions<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>>,
        ApprovedPermissionsMetadata
    ]>;
    /**
     * Initiates an incremental permission request that prompts for user approval.
     * Incremental permission requests allow the caller to replace existing and/or
     * add brand new permissions and caveats for the specified subject.
     *
     * Incremental permission request are merged with the subject's existing permissions
     * through a right-biased union, where the incremental permission are the right-hand
     * side of the merger. If both sides of the merger specify the same caveats for a
     * given permission, the caveats are merged using their specification's caveat value
     * merger property.
     *
     * Either this or {@link PermissionController.requestPermissions} should
     * always be used to grant additional permissions to a subject, unless user
     * approval has been obtained through some other means.
     *
     * Permissions are validated at every step of the approval process, and this
     * method will reject if validation fails.
     *
     * @see {@link ApprovalController} For the user approval logic.
     * @see {@link PermissionController.acceptPermissionsRequest} For the method
     * that _accepts_ the request and resolves the user approval promise.
     * @see {@link PermissionController.rejectPermissionsRequest} For the method
     * that _rejects_ the request and the user approval promise.
     * @param subject - The grantee subject.
     * @param requestedPermissions - The requested permissions.
     * @param options - Additional options.
     * @param options.id - The id of the permissions request. Defaults to a unique
     * id.
     * @param options.metadata - Additional metadata about the permission request.
     * @returns The granted permissions and request metadata.
     */
    requestPermissionsIncremental(subject: PermissionSubjectMetadata, requestedPermissions: RequestedPermissions, options?: {
        id?: string;
        metadata?: Record<string, Json>;
    }): Promise<[
        Partial<SubjectPermissions<ExtractPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>>>,
        ApprovedPermissionsMetadata
    ] | []>;
    /**
     * Accepts a permissions request created by
     * {@link PermissionController.requestPermissions}.
     *
     * @param request - The permissions request.
     */
    acceptPermissionsRequest(request: PermissionsRequest): Promise<void>;
    /**
     * Rejects a permissions request created by
     * {@link PermissionController.requestPermissions}.
     *
     * @param id - The id of the request to be rejected.
     */
    rejectPermissionsRequest(id: string): Promise<void>;
    /**
     * Gets the subject's endowments per the specified endowment permission.
     * Throws if the subject does not have the required permission or if the
     * permission is not an endowment permission.
     *
     * @param origin - The origin of the subject whose endowments to retrieve.
     * @param targetName - The name of the endowment permission. This must be a
     * valid permission target name.
     * @param requestData - Additional data associated with the request, if any.
     * Forwarded to the endowment getter function for the permission.
     * @returns The endowments, if any.
     */
    getEndowments(origin: string, targetName: ExtractEndowmentPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability'], requestData?: unknown): Promise<Json>;
    /**
     * Executes a restricted method as the subject with the given origin.
     * The specified params, if any, will be passed to the method implementation.
     *
     * ATTN: Great caution should be exercised in the use of this method.
     * Methods that cause side effects or affect application state should
     * be avoided.
     *
     * This method will first attempt to retrieve the requested restricted method
     * implementation, throwing if it does not exist. The method will then be
     * invoked as though the subject with the specified origin had invoked it with
     * the specified parameters. This means that any existing caveats will be
     * applied to the restricted method, and this method will throw if the
     * restricted method or its caveat decorators throw.
     *
     * In addition, this method will throw if the subject does not have a
     * permission for the specified restricted method.
     *
     * @param origin - The origin of the subject to execute the method on behalf
     * of.
     * @param targetName - The name of the method to execute. This must be a valid
     * permission target name.
     * @param params - The parameters to pass to the method implementation.
     * @returns The result of the executed method.
     */
    executeRestrictedMethod(origin: OriginString, targetName: ExtractRestrictedMethodPermission<ControllerPermissionSpecification, ControllerCaveatSpecification>['parentCapability'], params?: RestrictedMethodParameters): Promise<Json>;
}
export {};
//# sourceMappingURL=PermissionController.d.cts.map