https://github.com/certainlach/hidfox

WebHID shim for Firefox
https://github.com/certainlach/hidfox

firefox webextension webhid webusb

Last synced: 12 months ago
JSON representation

WebHID shim for Firefox

• Host: GitHub
• URL: https://github.com/certainlach/hidfox
• Owner: CertainLach
• Created: 2023-05-28T20:34:05.000Z (about 3 years ago)
• Default Branch: master
• Last Pushed: 2023-08-09T15:39:08.000Z (almost 3 years ago)
• Last Synced: 2025-06-20T03:31:13.316Z (12 months ago)
• Topics: firefox, webextension, webhid, webusb
• Language: Rust
• Homepage:
• Size: 322 KB
• Stars: 16
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc

Awesome Lists containing this project

README

          
= HIDFox

Firefox WebHID API support through webextension native messaging.

== Demo

:paramV: 

include::docs/youtube.adoc[]

ifdef::env-github[]

image:https://img.youtube.com/vi/yNaiQO94_sQ/maxresdefault.jpg[link=https://youtu.be/yNaiQO94_sQ]

endif::[]

ifndef::env-github[]

video::yNaiQO94_sQ[youtube]

endif::[]

Demo is outdated, the UI is much more polished now.

== Security

Consider it dangerous and harmful for now. You can try to use it, still.

=== Current concerns:

Page has access to the Hid/HidDevice objects::

Sensitive information here is protected by private fields (#name) and symbols.

Is this good enough? Maybe all of the sensitive objects should be passed as a closure?

Anyway, even injected script should only access non-sensitive information.

For devices, ids hash is used, and this may be used for unique user identification (If user has allowed hid access to the page),

but not for system information disclosure

Page may intercept/inject WindowMessageChannel data::

Uh oh. Content script should block any AddForwarded calls from the injected script, and should not send any sensitive

info (See the first concern).

User error::

Some considerations are taken into account, there should be an ability to not remember device access, there is an delay

before allowing device access button activates, to prevent misclicks.

In case of device not found - there is no immediate rejection, user should reject device access themselves, so the page

may not identify user by querying accessible devices.

== Performance

None. The protocol is awful for now, do not expect it to transfer large amounts of data quickly.

Every packet is serialized to json, and has at least 3 hops:

* Injected -> Content (No serialization/deserialization. Message object is passed between 2 isolates)

* Content -> Background (Quick serialization)

* Background -> Native (JSON serialization + JSON deserialization)

Every byte array is serialized as JSON array. At least base64 should be used.

Binary format is not possible, as background<->native communication may only use utf8. Maybe implement base127?

HID:

ifdef::env-github[]

image:docs/hid.png[]

endif::[]

ifndef::env-github[]

[mermaid, target=docs/hid, format=png]

....

sequenceDiagram

    participant I as Injected

    participant N as Native

    participant B as Background

    participant P as Popup

    actor U as User

    I->>+B: OpenNative

    note over B: Spawns native

    B->>+N: OpenFromInject

    N->>-B: [response]

    B->>-I: [response]

    I->>+N: SubscribeHid

    N->>-I: [response]

    par Hid device watcher

        loop Processing

            note over N: Refreshes list

            N->>+B: StorageGet(allowed)

            B->>-N: [response]

            N-)I: AddedDevice

            N-)I: RemovedDevice

            break Force refresh

                I->>+N: PollRefresh

                N->>-I: [response]

            end

        end

    and Device access request

        I->>+N: RequestDevice

        N->>+B: OpenPopup

        %% Todo: open it from user click handler. Or wait for page actions to start behave correctly?

        note over B: Opens popup

        P-)U: Start displaying 

        B->>-N: [response]

        N->>+P: RequestAccess

        P->>+U: Requested device list

        alt Allows

            U->>P: [allows]

            P->>N: [response]

            N->>+B: StorageSet(add allowed)

            B->>-N: [response]

        else Disallows

            U->>-P: [disallows]

            P->>-N: [response]

        end

        N->>-I: [response]

    end

....

endif::[]

Hid device:

ifdef::env-github[]

image:docs/hid-device.png[]

endif::[]

ifndef::env-github[]

[mermaid, target=docs/hid-device, format=png]

....

sequenceDiagram

....

endif::[]

== Plans

TODO: Switch to popups, once https://bugzilla.mozilla.org/show_bug.cgi?id=1799344 lands

TODO: Use popups when available in case of about:config flag set

TODO: Settings

TODO: Security

TODO: Do not remember transient device ids

TODO: Ability to disable extension by default, whitelisting pages to have HID access.

TODO: Make it possible to support third-party extensions, I.e injection into metamask. Probably requires metamask

extension support?

== License

Not decided yet, code is not yet completed. For now consider this code source-available, and do not try to use it.