<pre class='metadata'>
Title: Relinquishing Permissions
Shortname: permissions-revoke
Level: 1
Status: CG-DRAFT
Group: WICG
Repository: jyasskin/permissions-revoke
URL: https://jyasskin.github.io/permissions-revoke
Editor: Jeffrey Yasskin, w3cid 72192, Google Inc. https://google.com/
!Tests: <a href=https://github.com/w3c/web-platform-tests/tree/master/permissions-revoke>web-platform-tests permissions-revoke/</a> (<a href=https://github.com/w3c/web-platform-tests/labels/permissions-revoke>ongoing work</a>)

Abstract: This specification extends the Permissions API to provide a way to relinquish permission to use powerful features.
</pre>

# Introduction # {#intro}

This document specifies a function to relinquish permissions that are no longer
needed.

# Revoke API # {#api}

<xmp class=idl>
partial interface Permissions {
  Promise<PermissionStatus> revoke(object permissionDesc);
};
</xmp>

When the <dfn for='Permissions' method>revoke(|permissionDesc|)</dfn> method is
invoked, the UA MUST run the following algorithm, passing the parameter
|permissionDesc|:

<ol class="algorithm">
1. Let |rootDesc| be the object |permissionDesc| refers to, [=converted to an
    IDL value=] of type {{PermissionDescriptor}}. If this throws an exception,
    return [=a promise rejected with=] that exception and abort these steps.
1. Let |typedDescriptor| be the object |permissionDesc| refers to, [=converted
    to an IDL value=] of <code>|rootDesc|.{{PermissionDescriptor/name}}</code>'s
    [=permission descriptor type=]. If this throws an exception, return [=a
    promise rejected with=] that exception and abort these steps.
1. Return [=a new promise=] |promise| and run the following steps [=in parallel=]:
    1. The UA now has [=new information about the user's intent|new
        information that the user intends=] to revoke permission to use the
        feature described by |typedDescriptor|.
    1. If any tasks run due to <a
        href="https://w3c.github.io/permissions/#reacting-to-revocation">Reacting to
        users revoking permission</a>, wait for them to finish.
    1. [=Queue a task=] to [=resolve=] |promise| with the result of
        <code><a idl
        for="Permissions">query(|permissionDesc|)</a></code>.

        Issue: This should pass |typedDescriptor| directly into the
        parallel part of query().

</ol>


# Security Considerations # {#security}

No security considerations have been identified.

# Privacy Considerations # {#privacy}

No privacy considerations have been identified.
