WebHID Standard Pull Request #172 Preview

1. Introduction

This section is non-normative.

A HID (Human Interface Device) is a type of device that takes input from or provides output to humans. It also refers to the HID protocol, a standard for bi-directional communication between a host and a device that is designed to simplify the installation procedure. The HID protocol was originally developed for USB devices but has since been implemented over many other protocols, including Bluetooth.

The web platform already supports input from many HID devices. Keyboards, pointing devices, and gamepads are all typically implemented using the HID protocol. However, this support relies on the operating system’s HID drivers that transform the HID input into high-level input APIs. Devices that are not well supported by the host’s HID driver are often inaccessible to web pages. Similarly, the outputs on most devices that are not supported by the host’s HID driver are inaccessible.

See also the related Explainer document.

2. Motivating Applications

This section is non-normative.

2.1. Niche devices

The most common classes of HID input devices are already well-supported on the web platform through existing high-level input APIs. For instance, mouse input is accessible through PointerEvent and keyboard input is accessible through KeyboardEvent. Input from these devices is handled using the host’s native HID driver and typically does not require device-specific drivers or configuration to work correctly. WebHID is not intended for devices like these that are already well-supported through high-level input APIs.

For some classes of HID devices, the web platform supports some features of the device but limits access to other features. For instance, [GAMEPAD] supports the input capabilities of most game controllers but does not support less common capabilities like LED indicators or audio. These features are often not well-supported by host APIs and adding support within the user agent can lead to significant complexity. WebHID would give applications an alternative when the functionality provided by the high-level API is incomplete.

Many HID devices are not supported through any web platform API. The HID specification describes a wide array of devices that could be supported through HID, including virtual reality controls, flight simulators, medical equipment, and more. WebHID would allow these devices to be used without requiring additional drivers or modification to the user agent.

2.2. Prototyping, hobbyists, and educational devices

HID is attractive for prototyping and hobbyist applications because it allows devices to use the host’s generic HID driver instead of requiring a driver for each host where the device will be used. The simplified installation procedure also makes it easier for educators to deploy a device to a classroom of students without modifying the system configuration on each host. Providing access to HID devices through the web platform would further reduce installation requirements, particularly for devices that are currently only supported through host-specific applications.

3. Security and Privacy Considerations

This section is non-normative.

3.1. Abusing Access to a Device

HID peripherals may expose powerful functionality that should not be made accessible to the page without explicit consent from the user. For instance, a HID peripheral may have sensors that allow it to collect information about its surroundings. A device may store private information that should not be revealed or overwritten. Many devices expose functionality that allow the device firmware to be upgraded. Operating systems typically do not restrict access to HID devices from applications, and this access can occasionally be abused to damage the device or corrupt the data stored on it.

In some cases, a device may expose functionality that should not be accessible at all from a web page. Specific devices may be blocked by recognizing the device by its vendor ID and product ID and hiding such devices during enumeration. The report descriptor allows a device to describe its own capabilities, and this information can be used to block classes of devices even when the vendor ID and product ID cannot be known in advance. This can be accomplished by inspecting the HID usage values assigned to collections within the report descriptor; for instance, access to keyboard-like devices can be denied by denying access to devices that include a top-level collection with the HID usage for a keyboard.

To mitigate abuse, a device will not be made available to the page until the user has granted explicit access. Access must first be requested by the page and will be granted once the user has selected the device from a chooser displaying all available devices. Once a page has been granted access, an indicator will be displayed to indicate the device is in use.

3.2. Attacking a Device

The HID protocol is extremely versatile, and a wide variety of devices have been designed that take advantage of this versatility. As a result, there are many possibilities for how access to a device could allow a malicious page to damage the device itself. It is relatively common for HID peripherals to allow firmware updates to be sent using custom HID reports. Device manufacturers must take care to design the firmware upgrade mechanism to verify that the firmware binary is authentic, and should also protect against downgrades that could reduce the security of a device. Untrusted upgrades could be used to add new capabilities to a device or cause it to masquerade as an entirely different type of device.

Some devices may be damaged when inputs are provided outside of the expected range. For instance, the rumble feature on a gamepad could become damaged if a page sends an invalid rumble command.

In general, these types of attacks are device-specific and cannot be mitigated at the API level.

3.3. Attacking the Host

If a malicious page gains access to a device, in some cases this access can be used to attack the host. A major concern is whether the device can be used to generate trusted input events. These events serve as a proxy for user intent and can be used to access more powerful web platform features.

Mice and keyboards are typically implemented as HID peripherals, and are also capable of generating trusted input. A HID keyboard or mouse may contain advanced features like programmable macros, which store a sequence of inputs and allow the sequence to be played back at a later time. Device manufacturers must take care to design such features in a way that would prevent a malicious app from reprogramming the device with an unexpected input sequence, and must also protect against triggering macro playback without the user’s explicit consent.

3.4. Mitigation

To mitigate security and privacy risks, it is recommended that user agents implement a chooser-based flow for requesting device access. When a page requests access to a HID device, the user agent should display a dialog that informs the user that the page wants to access a device. The dialog should display a list of connected HID devices and ask the user to select a device that will be exposed to the page. To reduce the possibility of accidental clicks, the dialog should require two separate interactions: one interaction to select the device from the list and a second interaction to confirm the selection and dismiss the dialog.

4. Extensions to the `Navigator` interface

[SecureContext] partial interface Navigator {
    [SameObject] readonly attribute HID hid;
};

4.1. `hid` attribute

When getting, the hid attribute always returns the same instance of the HID object.

5. Extensions to the `WorkerNavigator` interface

[Exposed=(DedicatedWorker,ServiceWorker), SecureContext]
partial interface WorkerNavigator {
    [SameObject] readonly attribute HID hid;
};

5.1. `hid` attribute

When getting, the hid attribute always returns the same instance of the HID object.

6. `HID` interface

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HID : EventTarget {
    attribute EventHandler onconnect;
    attribute EventHandler ondisconnect;
    Promise<sequence<HIDDevice>> getDevices();
    [Exposed=Window] Promise<sequence<HIDDevice>> requestDevice(
        HIDDeviceRequestOptions options);
};

Note: The user agent’s implement may choose to conditionally expose hid attribute of the Navigator when the relevant global object of the Navigator is ServiceWorkerGlobalScope. For example, in the Browser extension contexts of [browserext].

Instances of HID are created with the internal slots described in the following table:

Internal slot	Initial value	Description (non-normative)
`[[devices]]`	An empty ordered set	An ordered set of `HIDDevice` instances representing the HID interfaces currently available on the system

onconnect attribute, of type EventHandler: onconnect is an event handler IDL attribute for the connect event type.
ondisconnect attribute, of type EventHandler: ondisconnect is an event handler IDL attribute for the disconnect event type.

When a HID interface becomes available on the system, run the following steps:

A HID interface is a logical interface that can be used to communicate with a device over the HID protocol. Each HID interface has exactly one report descriptor that describes the set of reports supported by that interface. A single physical device may expose more than one HID interface. Devices with multiple HID interfaces run these steps once for each interface.

For example, USB devices are implemented as a collection of interfaces, each of which may specify an interface class. When a device has multiple USB interfaces that use the HID class, each interface is enumerated as a separate HID interface.

Let device be a HIDDevice.
Set device.[[vendorId]] to the vendor ID of the device that exposes the interface.
Set device.[[productId]] to the product ID of the device that exposes the interface.
Set device.[[productName]] to the product name of the device that exposes the interface.
Set device.[[collections]] to the result of parsing the Report descriptor.
Let hid be the result of calling device’s relevant global object’s Navigator object’s hid getter if device’s relevant global object is a Window object, otherwise be the result of calling device’s relevant global object’s WorkerNavigator object’s hid getter.
Append device to hid.[[devices]].
If the user has allowed the site to access device as the result of a previous call to requestDevice(), then queue a global task on the relevant global object of hid using the HID device task source to fire an event named connect at hid using HIDConnectionEvent with its device attribute initialized to device.

To parse the report descriptor, run the following steps:

The system will typically read the report descriptor byte sequence for each HID interface when a device is first connected and cache the values in the system registry. If the report descriptor is not available but the system provides information that can be used to reconstruct the layout of each report, the user agent may use an alternate algorithm instead of parsing the report descriptor.

The report descriptor format is described in [USBIF-HID-CLASS] section 6.2.2. The algorithm below is intended to implement the same parsing algorithm described in that section.

The report descriptor contains three classes of items. Main items are used to define and group data fields. Global items and Local items describe the data fields. Local items define characteristics that only apply to the next Main item, while Global items define characteristics that affect all subsequently defined Main items.

Each item has an item data field containing 0, 1, 2, or 4 bytes of data associated with the item and a bSize field that describes how many bytes are used to store the item data field. Each item also has a tag that identifies its type.

Let items be the result of converting the report descriptor byte sequence into a list of Main items, Global items, and Local items.
Initialize collections to be an empty sequence of HIDCollectionInfo.
Initialize ancestors to be an empty list.
Initialize localState to be an empty ordered map.
Initialize usages to be an empty sequence of unsigned long.
Initialize stringIndices to be an empty list.
Initialize globalStack to be an empty stack.
Initialize initialGlobalState to be an empty ordered map.
Initialize reportId to 0.
Set initialGlobalState["unitSystem"] to "none".
Set initialGlobalState["unitExponent"] to 0.
Set initialGlobalState["unitFactorLengthExponent"] to 0.
Set initialGlobalState["unitFactorMassExponent"] to 0.
Set initialGlobalState["unitFactorTimeExponent"] to 0.
Set initialGlobalState["unitFactorTemperatureExponent"] to 0.
Set initialGlobalState["unitFactorCurrentExponent"] to 0.
Set initialGlobalState["unitFactorLuminousIntensityExponent"] to 0.
Set initialGlobalState["logicalMinimum"] to 0.
Set initialGlobalState["logicalMaximum"] to 0.
Set initialGlobalState["physicalMinimum"] to 0.
Set initialGlobalState["physicalMaximum"] to 0.
Push initialGlobalState onto globalStack.
For each item of items:

Note: Main items are described in [USBIF-HID-CLASS] sections 6.2.2.4 through 6.2.2.6. An item with the Input tag, Output tag, or Feature tag defines a field within an input, output, or feature report. The item data field of a Main item with an Input tag, Output tag, or Feature tag is a bit field containing several boolean parameters describing the data field. An item with the Collection tag defines a new collection nested within the current collection, or a new top-level collection if there is no current collection. The item data field of a Main item with a Collection tag contains the collection type. An item with the End Collection tag closes the current collection.
- If item is a Main item:
  1. If item has the Input tag, Output tag, or Feature tag:
    1. Let globalState be the last item of globalStack.
    2. Let reportId be globalState["reportId"].
    3. Let reportItem be the result of creating a HID report item with item, localState, globalState, usages, and strings.
    4. For each collection of ancestors:
      1. Let reports be:
        
        collection["inputReports"] if item has the Input tag,
        
        collection["outputReports"] if item has the Output tag, or
        
        collection["featureReports"] if item has the Feature tag.
      2. If reports contains an item with its reportId attribute equal to reportId, then let report be that item.
        
        Otherwise:
        
        Let report be a new HIDReportInfo dictionary.
        
        Set report["reportId"] to reportId.
        
        Set report["items"] to an empty sequence of HIDReportItem.
        
        Append report to reports.
      3. Append reportItem to report["items"].
  2. If item has the Collection tag:
    1. Let collection be a new HIDCollectionInfo dictionary.
    2. Let usage be the first item of usages.
    3. If the size of usages is greater than 1, remove the first item of usages.
    4. Set collection["usagePage"] to globalState["usagePage"].
    5. Set collection["usage"] to usage.
    6. Set collection["type"] to the value representing the collection’s type.
    7. Set collection["children"] to an empty sequence of HIDCollectionInfo.
    8. Set collection["inputReports"] to an empty sequence of HIDReportInfo.
    9. Set collection["outputReports"] to an empty sequence of HIDReportInfo.
    10. Set collection["featureReports"] to an empty sequence of HIDReportInfo.
    11. If ancestors is empty, append collection to collections.
      
      Otherwise:
      1. Let parent be the last item of ancestors.
      2. Append collection to parent["children"].
    12. Append collection to ancestors.
  3. If item has the End Collection tag, then remove the last item of ancestors.
  4. Set localState to be an empty ordered map.
  5. Set usages to be an empty sequence of unsigned long.
    
    Note: Global items are described in section 6.2.2.7. An item with the Usage Page tag, Logical Minimum tag, Logical Maximum tag, Physical Minimum tag, Physical Maximum tag, Unit Exponent tag, Unit tag, Report Size tag, Report ID tag, or Report Count tag modifies the respective field of the global item state table. An item with the Push tag pushes a copy of the current global item state table onto the item state stack. An item with the Pop tag replaces the global item state table with the top of the item state stack. The global Report ID value is not affected when manipulating the item state stack.
  6. If item is a Global item:
    1. Let globalState be the last item of globalStack.
    2. Let value be the item data field interpreted as an unsigned long.
    3. If item has the Usage Page tag, then set globalState["usagePage"] to value.
    4. If item has the Logical Minimum tag, then set globalState["logicalMinimum"] to value.
    5. If item has the Logical Maximum tag, then set globalState["logicalMaximum"] to value.
    6. If item has the Physical Minimum tag, then set globalState["physicalMinimum"] to value.
    7. If item has the Physical Maximum tag, then set globalState["physicalMaximum"] to value.
    8. If item has the Report Size tag, then set globalState["reportSize"] to value.
    9. If item has the Report ID tag, then set globalState["reportId"] to value.
    10. If item has the Report Count tag, then set globalState["reportCount"] to value.
    11. If item has the Unit tag:
      1. Let nibbles be the result of interpreting value as a sequence of eight 4-bit signed two’s complement integers starting from the low-order bits.
      2. If nibbles[0] is:
        
        0, then set globalState["unitSystem"] to "none"
        
        1, then set globalState["unitSystem"] to "si-linear"
        
        2, then set globalState["unitSystem"] to "si-rotation"
        
        3, then set globalState["unitSystem"] to "english-linear"
        
        4, then set globalState["unitSystem"] to "english-rotation"
        
        -1, then set globalState["unitSystem"] to "vendor-defined"
        
        Otherwise, set globalState["unitSystem"] to "reserved"
      3. Set globalState["unitFactorLengthExponent"] to nibbles[1].
      4. Set globalState["unitFactorMassExponent"] to nibbles[2].
      5. Set globalState["unitFactorTimeExponent"] to nibbles[3].
      6. Set globalState["unitFactorTemperatureExponent"] to nibbles[4].
      7. Set globalState["unitFactorCurrentExponent"] to nibbles[5].
      8. Set globalState["unitFactorLuminousIntensityExponent"] to nibbles[6].
    12. If item has the Unit Exponent tag, then set globalState["unitExponent"] to the result of interpreting the lowest 4 bits of the item data field as a signed two’s complement integer.
    13. If item has the Push tag, then push a copy of globalState onto globalStack.
    14. If item has the Pop tag, then pop from globalStack.
  Note: Local items are described in section 6.2.2.8. An item with the Usage tag, Usage Minimum tag, Usage Maximum tag, String Index tag, String Minimum tag, or String Maximum tag modifies the respective field of the local item state table. The local item state is cleared after each Main item.
- If item is a Local item:
  1. Let value be the item data field interpreted as an unsigned long.
  2. If item has the Usage tag, Usage Minimum tag, or Usage Maximum tag, and item’s bSize field is 1 or 2:
    1. Let usageId be an unsigned short containing the lower 16 bits of value.
    2. Let globalState be the last item of globalStack.
    3. Set value to a HID usage composed of globalState["usagePage"] in the high order bits and usageId in the low order bits.
  3. If item has the Usage tag, then append value to usages.
  4. If item has the Usage Minimum tag, then set localState["usageMinimum"] to value.
  5. If item has the Usage Maximum tag, then set localState["usageMaximum"] to value.
  6. If item has the String Index tag, then append value to stringIndices.
  7. If item has the String Minimum tag, then set localState["stringMinimum"] to value.
  8. If item has the String Maximum tag, then set localState["stringMaximum"] to value.

To create a HID report item with item, localState, globalState, usages, and stringIndices, run the following steps:

Let reportItem be a new HIDReportItem dictionary.
Let value be the item data field interpreted as an unsigned long.
Let bitfield be a list of boolean values representing each of the bits of value, starting from the low-order bits.
Set reportItem["isConstant"] to bitfield[0].
Set reportItem["isArray"] to !bitfield[1].
Set reportItem["isAbsolute"] to !bitfield[2].
Set reportItem["wrap"] to bitfield[3].
Set reportItem["isLinear"] to !bitfield[4].
Set reportItem["hasPreferredState"] to !bitfield[5].
Set reportItem["hasNull"] to bitfield[6].
Set reportItem["isVolatile"] to bitfield[7].
Set reportItem["isBufferedBytes"] to bitfield[8].
Set reportItem["usages"] to usages.
Set reportItem["reportSize"] to globalState["reportSize"].
Set reportItem["reportCount"] to globalState["reportCount"].
Set reportItem["unitExponent"] to globalState["unitExponent"].
Set reportItem["unitSystem"] to globalState["unitSystem"].
Set reportItem["unitFactorLengthExponent"] to globalState["unitFactorLengthExponent"].
Set reportItem["unitFactorMassExponent"] to globalState["unitFactorMassExponent"].
Set reportItem["unitFactorTimeExponent"] to globalState["unitFactorTimeExponent"].
Set reportItem["unitFactorTemperatureExponent"] to globalState["unitFactorTemperatureExponent"].
Set reportItem["unitFactorCurrentExponent"] to globalState["unitFactorCurrentExponent"].
Set reportItem["unitFactorLuminousIntensityExponent"] to globalState["unitFactorLuminousIntensityExponent"].
Set reportItem["logicalMinimum"] to globalState["logicalMinimum"].
Set reportItem["logicalMaximum"] to globalState["logicalMaximum"].
Set reportItem["physicalMinimum"] to globalState["physicalMinimum"].
Set reportItem["physicalMaximum"] to globalState["physicalMaximum"].
Set reportItem["isRange"] to true if both "usageMinimum" and "usageMaximum" are in localState and localState["usageMinimum"] is less than or equal to localState["usageMaximum"], or false otherwise.
If reportItem["isRange"] is true, set reportItem["usageMinimum"] to localState["usageMinimum"].
If reportItem["isRange"] is true, set reportItem["usageMaximum"] to localState["usageMaximum"].
If "stringMinimum" is in localState and "stringMaximum" is in localState:
1. Append the items of the range from localState["stringMinimum"] to localState["stringMaximum"] to stringIndices.
For each stringIndex of stringIndices:
1. Let string be the result of reading the string descriptor at index stringIndex.
2. Append string to reportItem["strings"].
Return reportItem.

When a HID interface becomes unavailable on the system, run the following steps:

Let device be the HIDDevice in hid.[[devices]] representing the interface.
Let hid be the result of calling device’s relevant global object’s Navigator object’s hid getter if device’s relevant global object is a Window object, otherwise be the result of calling device’s relevant global object’s WorkerNavigator object’s hid getter.
Remove device from hid.[[devices]].
If the user has allowed the site to access device as the result of a previous call to requestDevice(), then queue a global task on the relevant global object of hid using the HID device task source to fire an event named disconnect at hid using HIDConnectionEvent with its device attribute initialized to device.

6.1. `getDevices()` method

The getDevices() method steps are:

Let promise be a new promise.
Let document be null.
If this’s relevant global object is a DedicatedWorkerGlobalScope or window object, set document to this’s relevant global object’s associated Document.
If this’s relevant global object is a ServiceWorkerGlobalScope object and the associated service worker client is window client, set document to the associated Document of the associated service worker client’s global object.
If document is null or document is not allowed to use the policy-controlled feature named "hid", reject promise with a "SecurityError" DOMException and return promise.
Run the following steps in parallel:
1. Let devices be an empty sequence of HIDDevice.
2. For each device of this.[[devices]]:
  1. If the user has allowed the site to access device as the result of a previous call to requestDevice() and device.[[state]] is not "forgotten", then append device to devices.
3. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with devices.
Return promise.

6.2. `requestDevice()` method

The requestDevice() permission dialog presents a list of connected devices and asks the user to select one.

If a device has multiple HID interfaces, the dialog may present only a single item that represents all the interfaces. When the user selects an item that represents multiple HID interfaces, the user agent must grant access to all the HID interfaces exposed by the device.

The requestDevice() method steps are:

Let promise be a new promise.
If this’s relevant global object’s associated Document is not allowed to use the policy-controlled feature named "hid", reject promise with a "SecurityError" DOMException and return promise.
If the relevant global object of this is not window, reject promise with a "NotSupportedError" DOMException and return promise.
If the relevant global object of this does not have transient activation, reject promise with a "SecurityError" DOMException and return promise.
If options["filters"] is present, then run the following steps for each filter of options["filters"]:
1. If filter is not a valid filter, then reject promise with a TypeError and return promise.
If options["exclusionFilters"] is present, then run the following steps:
1. If options["exclusionFilters"] is empty, then reject promise with a TypeError and return promise.
2. For each exclusionFilter of options["exclusionFilters"]:
  1. If exclusionFilter is not a valid filter, then reject promise with a TypeError and return promise.
Run the following steps in parallel:
1. Initialize availableDevices to be an empty list.
2. For each device of this.[[devices]]:
  1. If device matches any filter in options["filters"] and device does not match any filter in options["exclusionFilters"], then append device to availableDevices.
3. Prompt the user to grant the site access to a HID device by presenting them with the list of devices in availableDevices.
  
  Note: The user agent may modify the device list before presenting it to the user. For example, devices with multiple HID interfaces should be represented by a single item such that selecting the item grants access to all interfaces exposed by the device. Whether a device is implemented as a single interface or a collection of interfaces is an implementation detail that may not be known by the user and should not be considered relevant for device access permissions.
4. Let devices be an empty sequence of HIDDevice.
5. If the user does not choose a device, queue a global task on the relevant global object of this using the HID device task source to resolve promise with devices and abort these steps.
6. For each device of this.[[devices]]:
  1. If device represents a HID interface exposed by the chosen device, then set device.[[state]] to "closed" and append device to devices.
7. Queue a global task on the relevant global object of device using the HID device task source to resolve promise with devices.
Return promise.

6.2.1. `HIDDeviceRequestOptions` dictionary

dictionary HIDDeviceRequestOptions {
    required sequence<HIDDeviceFilter> filters;
    sequence<HIDDeviceFilter> exclusionFilters;
};

filters member, of type sequence<HIDDeviceFilter>: Filters for HID devices.
exclusionFilters member, of type sequence<HIDDeviceFilter>: Exclusion filters for HID devices.

6.2.2. `HIDDeviceFilter` dictionary

dictionary HIDDeviceFilter {
    unsigned short vendorId;
    unsigned short productId;
    unsigned short usagePage;
    unsigned short usage;
};

vendorId member, of type unsigned short: The vendor ID to match.
productId member, of type unsigned short: The product ID to match. If the vendorId member is not present, productId is ignored.
usagePage member, of type unsigned short: The top-level collection usage page to match.
usage member, of type unsigned short: The top-level collection usage ID to match. If the usagePage member is not present, usage is ignored.

Device filters are used to narrow the list of devices presented to the user in the chooser dialog created by requestDevice(). When no filters are provided, all connected devices matching no exclusion filters are included. When one or more filters are provided, a device is included if any filter matches and no exclusion filters matches.

All HIDDeviceFilter members are optional. Each member specifies a rule. To match a HIDDeviceFilter, every rule must be satisfied. An empty HIDDeviceFilter matches any device.

Device ID rules are used to select devices by their vendor ID and product ID. This is useful when an application is only designed to work with a specific device, or otherwise relies on vendor-specific functionality. Including a vendorId rule causes the filter to only match devices with the specified vendor ID. If a productId rule is also included, the filter will only match devices with the specified vendor ID and product ID. productId is ignored if it is specified without a vendorId rule.

Usage rules are used to select devices by the HID usages assigned to the top-level collections of the device. This is useful when an application is designed to work with a standard class of device. To match a device, at least one of the device’s collections must match every usage rule. Including a usagePage rule causes the filter to only match if the device contains a collection with the specified usage page. If a usage rule is also included, the filter will only match devices with the specified usage page and usage ID. usage is ignored if it is specified without a usagePage rule.

Device ID rules and usage rules may be combined. For instance, an application may want to match devices from a particular vendor, but only devices that implement a specific device class.

The exclusionFilters option allows an application to exclude some devices presented to the user from the chooser dialog created by requestDevice() that are known to not work as expected, even though they implement a specific device class for instance.

A HIDDeviceFilter filter is a valid filter if these steps return true:

If filter is empty, then return false.
If filter["productId"] is present and filter["vendorId"] is not present, then return false.
If filter["usage"] is present and filter["usagePage"] is not present, then return false.
Return true.

A HIDDevice device matches any filter in a sequence filters of HIDDeviceFilter if these steps return true:

If filters is empty, then return true.
For each filter of filters:
1. If filter matches the device IDs of device and filter matches any collection of device, then return true.
Return false.

A HIDDeviceFilter filter matches the device IDs of device if these steps return true:

If "vendorId" is in filter:
1. If filter["vendorId"] is not equal to device.vendorId, then return false.
2. If "productId" is in filter and filter["productId"] is not equal to device.productId, then return false.
Return true.

A HIDDeviceFilter filter matches any collection of device if these steps return true:

For each collection of device.collections:
1. If filter matches the collection collection then return true.
Return false.

A HIDDeviceFilter filter matches the collection collection if these steps return true:

If "usagePage" is in filter:
1. If filter["usagePage"] is not equal to collection.usagePage, then return false.
2. If "usage" is in filter and filter["usage"] is not equal to collection.usage, then return false.
Return true.

7. `HIDDevice` interface

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDDevice : EventTarget {
    attribute EventHandler oninputreport;
    readonly attribute boolean opened;
    readonly attribute unsigned short vendorId;
    readonly attribute unsigned short productId;
    readonly attribute DOMString productName;
    readonly attribute FrozenArray<HIDCollectionInfo> collections;
    Promise<undefined> open();
    Promise<undefined> close();
    Promise<undefined> forget();
    Promise<undefined> sendReport([EnforceRange] octet reportId, BufferSource data);
    Promise<undefined> sendFeatureReport(
        [EnforceRange] octet reportId,
        BufferSource data);
    Promise<DataView> receiveFeatureReport([EnforceRange] octet reportId);
};

Methods on this interface typically complete asynchronously, queuing work on the HID device task source.

Instances of HIDDevice are created with the internal slots described in the following table:

Internal slot	Initial value	Description (non-normative)
`[[state]]`	`"closed"`	Tracks the active state of the `HIDDevice`
`[[vendorId]]`	0	The vendor ID of the device
`[[productId]]`	0	The product ID of the device
`[[productName]]`	`""`	The product name of the device
`[[collections]]`	An empty sequence of `HIDCollectionInfo`	The top-level collections created by parsing the report descriptor
`[[pendingSendReportPromises]]`	An empty list	Pending `sendReport()` `Promise`s
`[[pendingSendFeatureReportPromises]]`	An empty list	Pending `sendFeatureReport()` `Promise`s
`[[pendingReceiveFeatureReportPromises]]`	An empty list	Pending `receiveFeatureReport()` `Promise`s

oninputreport attribute, of type EventHandler

oninputreport is an event handler IDL attribute for the inputreport event type.

opened attribute, of type boolean, readonly

A flag indicating that the HIDDevice is ready to transfer data.

The opened getter steps are:

If this.[[state]] is opened, then return true.
Return false.

vendorId attribute, of type unsigned short, readonly

A vendor ID is an unsigned short value assigned by a vendor ID source that identifies the manufacturer of a device.

The vendorId attribute is the vendor ID of the device. If the device has no vendor ID or the vendor ID cannot be accessed, the attribute MUST be 0.

The vendorId getter steps are:

Return this.[[vendorId]].

productId attribute, of type unsigned short, readonly

A product ID is an unsigned short value assigned by the manufacturer of the device that identifies the product.

The productId attribute is the product ID of the device. If the device has no product ID or the product ID cannot be accessed, the attribute MUST be 0.

The productId getter steps are:

Return this.[[productId]].

productName attribute, of type DOMString, readonly

A string identifying the product.

For USB HID devices, the product name SHOULD contain the value of the string descriptor at the index iProduct specified in the Device Descriptor. For Bluetooth HID devices, the product name SHOULD contain the value of the Device Name characteristic. If the device has no product name or the product name is empty or cannot be accessed, the attribute MUST return an empty string.

The productName string SHOULD NOT contain any identifiers like a serial number or Bluetooth device address that could be used to uniquely identify the device.

The productName getter steps are:

Return this.[[productName]].

collections attribute, of type FrozenArray<HIDCollectionInfo>, readonly

A sequence of HIDCollectionInfo representing the top-level collections in the report descriptor.

The collections getter steps are:

Return this.[[collections]].

Note: Top-level collections group items that serve similar purposes within the device. Applications look at the HID usage applied to top-level collections to identify devices. An application may not recognize a device if it does not follow the conventions for a particular type of device. Refer to [USBIF-HID-USAGE] for more information about the conventional behavior for standard HID devices.

When an input report is received from a device, run the following steps:

If the input report is a blocked report, abort these steps.
Let reportId be the report ID for this report, or 0 if the HID interface does not use report IDs.
Let data be a DataView created over the byte sequence representing the input report. If the HID interface uses report IDs, the byte sequence MUST NOT include the report ID byte.
Queue a global task on the relevant global object of this using the HID device task source to fire an event named inputreport at device using HIDInputReportEvent with its device attribute initialized to device, its reportId attribute initialized to reportId, and its data attribute initialized to data.

7.1. `open()` method

The open() method steps are:

Let promise be a new promise.
If this.[[state]] is not "closed", then reject promise with a "InvalidStateError" DOMException and return promise.
Set this.[[state]] to "opening".
Perform the following steps in parallel:
1. Invoke the operating system to open the HID device.
2. If this fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
3. Set this.[[state]] to "opened".
4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
Return promise.

7.2. `close()` method

The close() method steps are:

Let promise be a new promise.
If this.[[state]] is one of "forgotten", "forgetting", "opening", or "closing", then reject promise with a "InvalidStateError" DOMException and return promise.
Set this.[[state]] to "closing".
For each pendingPromise of this.[[pendingSendReportPromises]]:
1. Reject pendingPromise with an "AbortError" DOMException.
Empty this.[[pendingSendReportPromises]].
For each pendingPromise of this.[[pendingSendFeatureReportPromises]]:
1. Reject pendingPromise with an "AbortError" DOMException.
Empty this.[[pendingSendFeatureReportPromises]].
For each pendingPromise of this.[[pendingReceiveFeatureReportPromises]]:
1. Reject pendingPromise with an "AbortError" DOMException.
Empty this.[[pendingReceiveFeatureReportPromises]].
Perform the following steps in parallel:
1. Invoke the operating system to close the HID device and release any associated resources.
2. Set this.[[state]] to "closed".
3. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
Return promise.

7.3. `forget()` method

Note: The user agent may decide to combine permissions across APIs, for instance tracking WebHID + WebUSB device access under a unified low-level device access permission. This is why this method may also revoke additional (unspecified yet) permissions in the future.

The forget() method steps are:

Let promise be a new promise.
If this’s relevant global object’s associated Document is not fully active, then:
1. Reject promise with an "InvalidStateError" DOMException.
2. Return promise.
Perform the following steps in parallel:
1. For each device of this.[[devices]]:
  1. If device does not share device access permissions with the HIDDevice, then continue to the next device.
  2. Set device.[[state]] to "forgetting".
  3. For each pendingPromise of device.[[pendingSendReportPromises]]:
    1. Reject pendingPromise with an "AbortError" DOMException.
  4. Empty device.[[pendingSendReportPromises]].
  5. For each pendingPromise of device.[[pendingSendFeatureReportPromises]]:
    1. Reject pendingPromise with an "AbortError" DOMException.
  6. Empty device.[[pendingSendFeatureReportPromises]].
  7. For each pendingPromise of device.[[pendingReceiveFeatureReportPromises]]:
    1. Reject pendingPromise with an "AbortError" DOMException.
  8. Empty device.[[pendingReceiveFeatureReportPromises]].
  9. Invoke the user agent to revoke access to all the HID interfaces exposed by device.
  10. Set device.[[state]] to "forgotten".
2. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
Return promise.

7.4. `sendReport()` method

The sendReport() method is used to send an output report with the specified reportId and data. If the HID interface does not use report IDs, pass 0 instead of the report ID.

For HID interfaces that use report IDs, the report ID value 0 is reserved and should not be used.

The sendReport() method steps are:

Let promise be a new promise.
If this.[[state]] is not "opened", then reject promise with a "InvalidStateError" DOMException and return promise.
If reportId is 0 and the HID interface represented by this uses report IDs, or if reportId is not 0 and the interface does not use report IDs, then reject promise with a "TypeError" DOMException and return promise.
Append promise to this.[[pendingSendReportPromises]].
Perform the following steps in parallel:
1. If this report is a blocked report, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NotAllowedError" DOMException and abort these steps.
2. Invoke the operating system to send an output report with the specified reportId and data.
3. If this fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
Return promise.

7.5. `sendFeatureReport()` method

The sendFeatureReport() method is used to send a feature report with the specified reportId and data. If the HID interface does not use report IDs, pass 0 instead of the report ID.

For HID interfaces that use report IDs, the report ID value 0 is reserved and should not be used.

The sendFeatureReport() method steps are:

Let promise be a new promise.
If this.[[state]] is not "opened", then reject promise with a "InvalidStateError" DOMException and return promise.
If reportId is 0 and the HID interface represented by this uses report IDs, or if reportId is not 0 and the interface does not use report IDs, then reject promise with a "TypeError" DOMException and return promise.
Append promise to this.[[pendingSendFeatureReportPromises]].
Perform the following steps in parallel:
1. If this report is a blocked report, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NotAllowedError" DOMException and abort these steps.
2. Invoke the operating system to send a feature report with the specified reportId and data.
3. If this fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with undefined.
Return promise.

7.6. `receiveFeatureReport()` method

The receiveFeatureReport() method is used to request a feature report with the specified reportId. If the HID interface does not use report IDs, pass 0 instead of the report ID.

For HID interfaces that use report IDs, the report ID value 0 is reserved and should not be used.

The receiveFeatureReport() method steps are:

Let promise be a new promise.
If this.[[state]] is not "opened", then reject promise with a "InvalidStateError" DOMException and return promise.
If reportId is 0 and the HID interface represented by this uses report IDs, or if reportId is not 0 and the interface does not use report IDs, then reject promise with a "TypeError" DOMException and return promise.
Append promise to this.[[pendingReceiveFeatureReportPromises]].
Perform the following steps in parallel:
1. If this report is a blocked report, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NotAllowedError" DOMException and abort these steps.
2. Let data be a DataView created over the byte sequence representing the result of invoking the operating system to read a feature report with the specified reportId.
  
  Note: data will contain whatever report data was received from the operating system. If the device uses report IDs the first byte may be the report ID. This byte is included because the device may respond with other data in place of the report ID.
3. If reading the feature report fails for any reason, queue a global task on the relevant global object of this using the HID device task source to reject promise with a "NetworkError" DOMException and abort these steps.
4. Queue a global task on the relevant global object of this using the HID device task source to resolve promise with data.
Return promise.

8. `HIDConnectionEvent` interface

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDConnectionEvent : Event {
    constructor(DOMString type, HIDConnectionEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
};

device attribute, of type HIDDevice, readonly: The HIDDevice instance that represents the connected or disconnected device.

8.1. `HIDConnectionEventInit` dictionary

dictionary HIDConnectionEventInit : EventInit {
    required HIDDevice device;
};

device member, of type HIDDevice: The device associated with the event.

9. `HIDInputReportEvent` interface

[Exposed=(DedicatedWorker,ServiceWorker,Window), SecureContext]
interface HIDInputReportEvent : Event {
    constructor(DOMString type, HIDInputReportEventInit eventInitDict);
    [SameObject] readonly attribute HIDDevice device;
    readonly attribute octet reportId;
    readonly attribute DataView data;
};

device attribute, of type HIDDevice, readonly: The HIDDevice instance that represents the HID interface that sent the input report.
reportId attribute, of type octet, readonly: The one-byte identification prefix for this report, or 0 if the HID interface does not use report IDs.
data attribute, of type DataView, readonly: A DataView containing the data from the input report, excluding the reportId byte if the HID interface uses report IDs.

9.1. `HIDInputReportEventInit` dictionary

dictionary HIDInputReportEventInit : EventInit {
    required HIDDevice device;
    required octet reportId;
    required DataView data;
};

device member, of type HIDDevice: The device associated with the event.
reportId member, of type octet: The report ID for the input report.
data member, of type DataView: The data for the input report.

10. `HIDCollectionInfo` dictionary

dictionary HIDCollectionInfo {
    unsigned short usagePage;
    unsigned short usage;
    octet type;
    sequence<HIDCollectionInfo> children;
    sequence<HIDReportInfo> inputReports;
    sequence<HIDReportInfo> outputReports;
    sequence<HIDReportInfo> featureReports;
};

When a device is first connected to the system, the system must retrieve the report descriptor for each HID interface exposed by the device. The Report descriptor is a byte sequence that can be expanded into a hierarchical data structure describing the layout of each report supported by the device. The elements of this data structure are called items. Groups of items that share a relationship are called collections.

A HIDCollectionInfo object represents a single collection within the report descriptor. When a collection contains nested collections, the nested collections are included as elements of children.

The inputReports, outputReports, and featureReports attributes contain sequences of HIDReportInfo that give information about each report described within this collection. For a top-level collection, the HIDReportInfo represents a flattened view of all items that compose the report. The flattened view interleaves items contained in nested collections with items contained within the top-level collection. For a nested collection, the HIDReportInfo includes only the items contained within the collection and its nested collections.

usagePage member, of type unsigned short

The usage page component of the HID usage associated with this collection.

HID usages are constants that can be interpreted by an application to identify the purpose and meaning of an item or collection. A HID usage is an unsigned long value composed of an unsigned short usage page in the high order bits and an unsigned short usage ID in the low order bits. Standard HID usage values are described in [USBIF-HID-CLASS] and other documents published by the USB Implementers Forum.

The HID usages of the top-level collections exposed by the device is used to identify the general device type.

usage member, of type unsigned short

The usage ID component of the HID usage associated with this collection.

A usage ID is used to select an individual HID usage on a usage page. By convention, usage IDs 0x01 through 0x1F are reserved for top-level collections.

type member, of type octet

A value representing the collection type.

Collection type	Value
Physical	0x00
Application	0x01
Logical	0x02
Report	0x03
Named Array	0x04
Usage Switch	0x05
Usage Modified	0x06
Reserved for future use	0x07 to 0x7F
Vendor-defined	0x80 to 0xFF

Each collection type describes a different type of relationship among the grouped items. Refer to [USBIF-HID-CLASS] section 6.2.2.6 for more information about collection types.

children member, of type sequence<HIDCollectionInfo>

A sequence of HIDCollectionInfo representing the collections nested within this collection.

inputReports member, of type sequence<HIDReportInfo>

A sequence of HIDReportInfo representing the input reports described within this collection.

outputReports member, of type sequence<HIDReportInfo>

A sequence of HIDReportInfo representing the output reports described within this collection.

featureReports member, of type sequence<HIDReportInfo>

A sequence of HIDReportInfo representing the feature reports described within this collection.

11. `HIDReportInfo` dictionary

dictionary HIDReportInfo {
    octet reportId;
    sequence<HIDReportItem> items;
};

A HIDReportInfo represents one input, output, or feature report within the report descriptor.

reportId member, of type octet: A HID interface uses report IDs if it prepends a one-byte identification prefix to each report transfer. The reportId member is the prefix for this report if the interface uses report IDs, or 0 otherwise.
items member, of type sequence<HIDReportItem>: A sequence of HIDReportItem representing the fields of this report.

12. `HIDReportItem` dictionary

dictionary HIDReportItem {
    boolean isAbsolute;
    boolean isArray;
    boolean isBufferedBytes;
    boolean isConstant;
    boolean isLinear;
    boolean isRange;
    boolean isVolatile;
    boolean hasNull;
    boolean hasPreferredState;
    boolean wrap;
    sequence<unsigned long> usages;
    unsigned long usageMinimum;
    unsigned long usageMaximum;
    unsigned short reportSize;
    unsigned short reportCount;
    byte unitExponent;
    HIDUnitSystem unitSystem;
    byte unitFactorLengthExponent;
    byte unitFactorMassExponent;
    byte unitFactorTimeExponent;
    byte unitFactorTemperatureExponent;
    byte unitFactorCurrentExponent;
    byte unitFactorLuminousIntensityExponent;
    long logicalMinimum;
    long logicalMaximum;
    long physicalMinimum;
    long physicalMaximum;
    sequence<DOMString> strings;
};

isAbsolute member, of type boolean: true if the data is absolute (based on a fixed origin), or false if the data is relative (indicating the change in value from the last report).
isArray member, of type boolean: true if the item creates array data fields in reports where each data field contains an index corresponding to a pressed button or key, or false if the item creates variable data fields in reports where each data field contains a value.
isBufferedBytes member, of type boolean: true if the item emits a fixed-sized stream of bytes, or false if the item is a numeric quantity.
isConstant member, of type boolean: true if the item is a static read-only field and cannot be modified, or false if the item defines report fields that contain modifiable device data.
isLinear member, of type boolean: true if the item represents a linear relationship between what is measured and what is reported, or false if the data has been processed in some way.
isRange member, of type boolean: true if the item assigns usages from a HID usage range defined by usageMinimum and usageMaximum, or false if the item has a sequence of HID usage values in usages.
isVolatile member, of type boolean: true if the item value can change without host interaction, or false if the item value should only be changed by the host.
Only used for Feature and Output items.
hasNull member, of type boolean: true if the item has a null state in which it is not sending meaningful data, or false if it does not have a null state. When in a null state, the item will report a value outside of the specified logicalMinimum and logicalMaximum.
hasPreferredState member, of type boolean: true if the item has a preferred state to which it will return when the user is not physically interacting with the control, or false if the item does not have a preferred state.
wrap member, of type boolean: true if the item value rolls over when reaching either the extreme high or low value, or false if the item value does not roll over.
usages member, of type sequence<unsigned long>: If isRange is true or this item has no associated HID usage values, then usages MUST be undefined.
If isRange is false then usages is a sequence of HID usage values associated with this item.
usageMinimum member, of type unsigned long: If isRange is true then usageMinimum contains the minimum HID usage value in the usage range associated with this item.
If isRange is false then usageMinimum MUST be undefined.
usageMaximum member, of type unsigned long: If isRange is true then usageMaximum contains the maximum HID usage value in the usage range associated with this item.
If isRange is false then usageMaximum MUST be undefined.
reportSize member, of type unsigned short: The size of each report data field in bits. The reportSize MUST be greater than 0.
reportCount member, of type unsigned short: The number of fields included in the report for this item. The reportCount MUST be greater than 0.
unitExponent member, of type byte: The value of the unit exponent, or 0 if the item has no unit definition.
unitSystem member, of type HIDUnitSystem: A HIDUnitSystem enum value specifying the unit system for the unit definition, or "none" if the item has no unit definition.
unitFactorLengthExponent member, of type byte: The value of the exponent for the length unit (centimeters, radians, inch, or degrees) in the unit definition, or 0 if the item has no unit definition.
unitFactorMassExponent member, of type byte: The value of the exponent for the mass unit (gram or slug) in the unit definition, or 0 if the item has no unit definition.
unitFactorTimeExponent member, of type byte: The value of the exponent for the time unit (seconds) in the unit definition, or 0 if the item has no unit definition.
unitFactorTemperatureExponent member, of type byte: The value of the exponent for the temperature unit (Kelvin or degrees Fahrenheit) in the unit definition, or 0 if the item has no unit definition.
unitFactorCurrentExponent member, of type byte: The value of the exponent for the electrical current unit (Ampere) in the unit definition, or 0 if the item has no unit definition.
unitFactorLuminousIntensityExponent member, of type byte: The value of the exponent for the luminous intensity unit (Candela) in the unit definition, or 0 if the item has no unit definition.
logicalMinimum member, of type long: The minimum extent of this item in logical units. This is the minimum value that a variable or array item will report.
logicalMaximum member, of type long: The maximum extent of this item in logical units. This is the maximum value that a variable or array item wll report.
physicalMinimum member, of type long: The minimum value for the physical extent of this item. This represents the logicalMinimum with units applied to it.
physicalMaximum member, of type long: The maximum value for the physical extent of this item. This represents the logicalMaximum with units applied to it.
strings member, of type sequence<DOMString>: The strings associated with this item, or an empty sequence if no strings are associated with this item.

13. `HIDUnitSystem` enum

[USBIF-HID-CLASS] section 6.2.2.7 defines four standard unit systems: SI Linear, SI Rotation, English Linear, and English Rotation. Each item uses one of these four unit systems, a vendor-defined unit system, or no unit system.

enum HIDUnitSystem {
    "none", "si-linear", "si-rotation", "english-linear",
    "english-rotation", "vendor-defined", "reserved"
};

"none": No unit system. Indicates that the item does not have a unit definition.
"si-linear": The SI Linear unit system uses centimeter, gram, second, Kelvin, Ampere, Candela.
"si-rotation": The SI Rotation unit system uses radian, gram, second, Kelvin, Ampere, Candela.
"english-linear": The English Linear unit system uses inch, slug, second, degree Fahrenheit, Ampere, Candela.
"english-rotation": The English Rotation unit system uses degree, slug, second, degree Fahrenheit, Ampere, Candela.
"vendor-defined": A vendor-defined unit system.
"reserved": Indicates that the device used a reserved value for its unit system.

14. Usage Examples

Retrieve the list of devices that are accessible to the page. By default, nothing is accessible since the page has not been granted permission to access any devices.

document.addEventListener('DOMContentLoaded', async () => {
  let devices = await navigator.hid.getDevices();
  devices.forEach(device => {
    console.log(`HID: ${device.productName}`);
  });
});

navigator.hid.addEventListener('connect', ({device}) => {
  console.log(`HID connected: ${device.productName}`);
});

navigator.hid.addEventListener('disconnect', ({device}) => {
  console.log(`HID disconnected: ${device.productName}`);
});

Devices are not accessible through getDevices() and will not generate connection events until permission has been granted to access the device. The page may request permission using requestDevice(). In this example, the page requests access to a device with vendor ID 0xABCD. The device must also have a collection with usage page Consumer (0x000C) and usage ID Consumer Control (0x0001). The device with product ID 0x1234 has been reported as malfunctioning.

let requestButton = document.getElementById("request-hid-device");
requestButton.addEventListener("click", async () => {
  let device;
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0xabcd,
          usagePage: 0x000c,
          usage: 0x0001,
        },
      ],
      exclusionFilters: [
        {
          vendorId: 0xabcd,
          productId: 0x1234,
        }
      ],
    });
    device = devices[0];
  } catch (error) {
    console.log("An error occurred.");
  }

  if (!device) {
    console.log("No device was selected.");
  } else {
    console.log(`HID: ${device.productName}`);
  }
});

device.oninputreport = ({device, reportId, data}) => {
  console.log(`Input report ${reportId} from ${device.productName}:`,
              new Uint8Array(data.buffer));
};

if (!device.opened)
  await device.open();

Send an output report.

try {
  if (!device.opened)
    await device.open();

  const outputReportData = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
  await device.sendReport(0x05, outputReportData);
  console.log("Output report sent");
} catch (error) {
  console.log("An error occurred.")
}

Read and write a feature report.

try {
  if (!device.opened)
    await device.open();

  const oldFeatureData = await device.receiveFeatureReport(0x80);
  console.log("Feature report received:", new Uint8Array(oldFeatureData.buffer));

  const newFeatureData = new Uint8Array([0x12, 0x34, 0x56, 0x78]);
  await device.sendFeatureReport(0x80, newFeatureData);
  console.log("Feature report sent");
} catch (error) {
  console.log("An error occurred.")
}

15. The HID Blocklist

This specification relies on a blocklist file in the https://github.com/whatwg/hid repository to restrict the set of HID devices a website can access.

The result of parsing the blocklist at a URL url is a sequence of dictionary objects produced by fetching url and parsing its contents as JSON.

The HID blocklist is the result of parsing the blocklist at https://github.com/whatwg/hid/blob/main/blocklist.txt

A report is a blocked report if the following steps return true:

For each rule of the HID blocklist:
1. If the report is blocked by a blocklist rule rule then return true.
Return false.

A report is blocked by a blocklist rule rule if the following steps return true:

Let reportId be the report ID of the report, or 0 if the HID interface does not use report IDs.
Let reportType be "input" if the report is an input report, "output" if the report is an output report, or "feature" if the report is a feature report.
Let collection be the top-level collection that contains the report.
If rule contains "vendor" and rule["vendor"] is not device.vendorId, return false.
If rule contains "product" and rule["product"] is not device.productId, return false.
If rule contains "reportId" and rule["reportId"] is not reportId, return false.
If rule contains "reportType" and rule["reportType"] is not reportType, return false.
If rule contains "usagePage" and rule["usagePage"] is not collection["usagePage"], return false.
If rule contains "usage" and rule.["usage"] is not collection["usage"], return false.
Return true.

16. Integrations

16.1. Permissions Policy

This specification defines a feature that controls whether the hid attribute is exposed on the Navigator object.

The feature name for this feature is "hid".

The default allowlist for this feature is 'self'.

Acknowledgments

Thanks to Feras Aldahlawi, François Beaufort, Jack Hsieh, Jeffrey Yasskin, Jonas Due Vesterheden, Kagami Sascha Rosylight, Marcos Cáceres, Peter Høy Andersen, Reilly Grant, Rob Pitkin, Ted Mielczarek, Thomas Steiner, Tim Steiner, and Vincent Scheib for being awesome.

This standard is written by Matt Reynolds (Google, mattreynolds@google.com).

Intellectual property rights

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.

WebHID (PR #172)

Abstract

1. Introduction

2. Motivating Applications

2.1. Niche devices

2.2. Prototyping, hobbyists, and educational devices

3. Security and Privacy Considerations

3.1. Abusing Access to a Device

3.2. Attacking a Device

3.3. Attacking the Host

3.4. Mitigation

4. Extensions to the Navigator interface

4.1. hid attribute

5. Extensions to the WorkerNavigator interface

5.1. hid attribute

6. HID interface

6.1. getDevices() method

6.2. requestDevice() method

6.2.1. HIDDeviceRequestOptions dictionary

6.2.2. HIDDeviceFilter dictionary

7. HIDDevice interface

7.1. open() method

7.2. close() method

7.3. forget() method

7.4. sendReport() method

7.5. sendFeatureReport() method

7.6. receiveFeatureReport() method

8. HIDConnectionEvent interface

8.1. HIDConnectionEventInit dictionary

9. HIDInputReportEvent interface

9.1. HIDInputReportEventInit dictionary

10. HIDCollectionInfo dictionary

11. HIDReportInfo dictionary

12. HIDReportItem dictionary

13. HIDUnitSystem enum

14. Usage Examples

15. The HID Blocklist

16. Integrations

16.1. Permissions Policy

Acknowledgments

Intellectual property rights

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

Non-Normative References

IDL Index

4. Extensions to the `Navigator` interface

4.1. `hid` attribute

5. Extensions to the `WorkerNavigator` interface

5.1. `hid` attribute

6. `HID` interface

6.1. `getDevices()` method

6.2. `requestDevice()` method

6.2.1. `HIDDeviceRequestOptions` dictionary

6.2.2. `HIDDeviceFilter` dictionary

7. `HIDDevice` interface

7.1. `open()` method

7.2. `close()` method

7.3. `forget()` method

7.4. `sendReport()` method

7.5. `sendFeatureReport()` method

7.6. `receiveFeatureReport()` method

8. `HIDConnectionEvent` interface

8.1. `HIDConnectionEventInit` dictionary

9. `HIDInputReportEvent` interface

9.1. `HIDInputReportEventInit` dictionary

10. `HIDCollectionInfo` dictionary

11. `HIDReportInfo` dictionary

12. `HIDReportItem` dictionary

13. `HIDUnitSystem` enum