{"id":28962912,"url":"https://github.com/certainlach/hidfox","last_synced_at":"2025-06-24T03:12:32.962Z","repository":{"id":188648358,"uuid":"646574655","full_name":"CertainLach/hidfox","owner":"CertainLach","description":"WebHID shim for Firefox","archived":false,"fork":false,"pushed_at":"2023-08-09T15:39:08.000Z","size":330,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-20T03:31:13.316Z","etag":null,"topics":["firefox","webextension","webhid","webusb"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CertainLach.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-05-28T20:34:05.000Z","updated_at":"2025-05-03T23:17:44.000Z","dependencies_parsed_at":"2023-08-16T09:20:48.421Z","dependency_job_id":null,"html_url":"https://github.com/CertainLach/hidfox","commit_stats":null,"previous_names":["certainlach/hidfox"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/CertainLach/hidfox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CertainLach%2Fhidfox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CertainLach%2Fhidfox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CertainLach%2Fhidfox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CertainLach%2Fhidfox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CertainLach","download_url":"https://codeload.github.com/CertainLach/hidfox/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CertainLach%2Fhidfox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261595786,"owners_count":23182250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["firefox","webextension","webhid","webusb"],"created_at":"2025-06-24T03:12:32.295Z","updated_at":"2025-06-24T03:12:32.940Z","avatar_url":"https://github.com/CertainLach.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"= HIDFox\n\nFirefox WebHID API support through webextension native messaging.\n\n== Demo\n\n:paramV: \ninclude::docs/youtube.adoc[]\nifdef::env-github[]\nimage:https://img.youtube.com/vi/yNaiQO94_sQ/maxresdefault.jpg[link=https://youtu.be/yNaiQO94_sQ]\nendif::[]\n\nifndef::env-github[]\nvideo::yNaiQO94_sQ[youtube]\nendif::[]\n\nDemo is outdated, the UI is much more polished now.\n\n== Security\n\nConsider it dangerous and harmful for now. You can try to use it, still.\n\n=== Current concerns:\n\nPage has access to the Hid/HidDevice objects::\nSensitive information here is protected by private fields (#name) and symbols.\n\nIs this good enough? Maybe all of the sensitive objects should be passed as a closure?\nAnyway, even injected script should only access non-sensitive information.\n\nFor devices, ids hash is used, and this may be used for unique user identification (If user has allowed hid access to the page),\nbut not for system information disclosure\n\nPage may intercept/inject WindowMessageChannel data::\nUh oh. Content script should block any AddForwarded calls from the injected script, and should not send any sensitive\ninfo (See the first concern).\n\nUser error::\nSome considerations are taken into account, there should be an ability to not remember device access, there is an delay\nbefore allowing device access button activates, to prevent misclicks.\n\nIn case of device not found - there is no immediate rejection, user should reject device access themselves, so the page\nmay not identify user by querying accessible devices.\n\n== Performance\n\nNone. The protocol is awful for now, do not expect it to transfer large amounts of data quickly.\n\nEvery packet is serialized to json, and has at least 3 hops:\n\n* Injected -\u003e Content (No serialization/deserialization. Message object is passed between 2 isolates)\n* Content -\u003e Background (Quick serialization)\n* Background -\u003e Native (JSON serialization + JSON deserialization)\n\nEvery byte array is serialized as JSON array. At least base64 should be used.\n\nBinary format is not possible, as background\u003c-\u003enative communication may only use utf8. Maybe implement base127?\n\nHID:\n\nifdef::env-github[]\nimage:docs/hid.png[]\nendif::[]\n\nifndef::env-github[]\n[mermaid, target=docs/hid, format=png]\n....\nsequenceDiagram\n    participant I as Injected\n    participant N as Native\n    participant B as Background\n    participant P as Popup\n    actor U as User\n\n    I-\u003e\u003e+B: OpenNative\n    note over B: Spawns native\n    B-\u003e\u003e+N: OpenFromInject\n    N-\u003e\u003e-B: [response]\n    B-\u003e\u003e-I: [response]\n\n    I-\u003e\u003e+N: SubscribeHid\n    N-\u003e\u003e-I: [response]\n\n    par Hid device watcher\n        loop Processing\n            note over N: Refreshes list\n\n            N-\u003e\u003e+B: StorageGet(allowed)\n            B-\u003e\u003e-N: [response]\n\n            N-)I: AddedDevice\n            N-)I: RemovedDevice\n\n            break Force refresh\n                I-\u003e\u003e+N: PollRefresh\n                N-\u003e\u003e-I: [response]\n            end\n        end\n    and Device access request\n        I-\u003e\u003e+N: RequestDevice\n        N-\u003e\u003e+B: OpenPopup\n        %% Todo: open it from user click handler. Or wait for page actions to start behave correctly?\n        note over B: Opens popup\n        P-)U: Start displaying \n        B-\u003e\u003e-N: [response]\n\n        N-\u003e\u003e+P: RequestAccess\n        P-\u003e\u003e+U: Requested device list\n        alt Allows\n            U-\u003e\u003eP: [allows]\n            P-\u003e\u003eN: [response]\n            N-\u003e\u003e+B: StorageSet(add allowed)\n            B-\u003e\u003e-N: [response]\n        else Disallows\n            U-\u003e\u003e-P: [disallows]\n            P-\u003e\u003e-N: [response]\n        end\n        N-\u003e\u003e-I: [response]\n    end\n....\nendif::[]\n\nHid device:\n\nifdef::env-github[]\nimage:docs/hid-device.png[]\nendif::[]\n\nifndef::env-github[]\n[mermaid, target=docs/hid-device, format=png]\n....\nsequenceDiagram\n....\nendif::[]\n\n== Plans\n\nTODO: Switch to popups, once https://bugzilla.mozilla.org/show_bug.cgi?id=1799344 lands\n\nTODO: Use popups when available in case of about:config flag set\n\nTODO: Settings\n\nTODO: Security\n\nTODO: Do not remember transient device ids\n\nTODO: Ability to disable extension by default, whitelisting pages to have HID access.\n\nTODO: Make it possible to support third-party extensions, I.e injection into metamask. Probably requires metamask\nextension support?\n\n== License\n\nNot decided yet, code is not yet completed. For now consider this code source-available, and do not try to use it.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcertainlach%2Fhidfox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcertainlach%2Fhidfox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcertainlach%2Fhidfox/lists"}