{"id":49608564,"url":"https://github.com/go-ctap/windows-proxy","last_synced_at":"2026-07-01T19:32:20.191Z","repository":{"id":355608326,"uuid":"994825239","full_name":"go-ctap/windows-proxy","owner":"go-ctap","description":"CTAPHID proxy for unprivileged access in Windows","archived":false,"fork":false,"pushed_at":"2026-05-04T12:56:56.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-04T14:37:26.217Z","etag":null,"topics":["authentication","authorization","ctap","ctap2","ctaphid","fido","fido2","hardware-token","hid"],"latest_commit_sha":null,"homepage":"","language":"Go","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/go-ctap.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-02T14:37:04.000Z","updated_at":"2026-05-04T12:55:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/go-ctap/windows-proxy","commit_stats":null,"previous_names":["go-ctap/windows-proxy"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/go-ctap/windows-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-ctap%2Fwindows-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-ctap%2Fwindows-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-ctap%2Fwindows-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-ctap%2Fwindows-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-ctap","download_url":"https://codeload.github.com/go-ctap/windows-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-ctap%2Fwindows-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35020870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["authentication","authorization","ctap","ctap2","ctaphid","fido","fido2","hardware-token","hid"],"created_at":"2026-05-04T14:02:52.586Z","updated_at":"2026-07-01T19:32:20.185Z","avatar_url":"https://github.com/go-ctap.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CTAP Windows proxy\n\n## Overview\n\nOn Windows, direct communication with FIDO2 tokens using the CTAP protocol (e.g., over HID) typically requires\nadministrator privileges. This can be a significant hurdle for applications that need to interact with\nFIDO2 authenticators without requiring the user to run the entire application with elevated rights.\n\nThis program addresses this limitation by acting as a **proxy service**. It is designed to:\n\n1. **Run as a Windows Service:** This allows the proxy to run with the necessary privileges to access HID devices\n   directly.\n2. **Listen on a Named Pipe:** It exposes a named pipe endpoint for inter-process communication.\n3. **Proxy CTAP Requests:** Client applications can send CTAP requests to this named pipe. The service then forwards\n   these requests to the actual FIDO2 HID device and returns the responses.\n\nThis architecture enables unprivileged applications to communicate with FIDO2 tokens. Specifically,\nmy [go-ctaphid](https://github.com/go-ctap/ctaphid) library is designed to leverage this proxy,\nallowing Go applications to interact with FIDO2 tokens on Windows without needing administrator rights for\nthe application itself.\n\nIn essence, this program provides a bridge for unprivileged CTAP access to FIDO2 tokens on Windows.\n\nOkay, here's a documentation draft for your proxy protocol based on the provided Go code.\n\n## HID Proxy Protocol Documentation\n\nThis document describes the communication protocol used between a client application and the HID Proxy service\nover a Windows Named Pipe.\n\n### 1. Overview\n\nThe protocol enables unprivileged applications to communicate with FIDO2 HID devices. It involves two main phases:\n\n1. **Control Phase:** The client sends structured messages to enumerate available FIDO2 devices and to select one\n   for proxying.\n2. **Proxy Phase:** Once a device is selected, the named pipe connection switches to a raw byte stream,\n   directly proxying CTAPHID packets between the client and the selected HID device.\n\n### 2. Transport\n\n*   **Named Pipe Path:** `\\\\.\\pipe\\ctaphid`\n   *   Clients connect to this named pipe to communicate with the proxy service.\n\n### 3. Message Structure (Control Phase)\n\nAll messages exchanged during the Control Phase follow this structure:\n\n| Field   | Size (bytes) | Description                                                      |\n|:--------|:-------------|:-----------------------------------------------------------------|\n| Command | 1            | The command ID (see [Commands](#4-commands-control-phase)).      |\n| Length  | 2            | Big-endian `uint16` representing the length of the `Data` field. |\n| Data    | `Length`     | Payload specific to the command. Often CBOR-encoded.             |\n\n**Data Encoding:** Unless otherwise specified, the `Data` payload for requests and responses that contain complex\nstructures (like device information or paths) is CBOR-encoded.\n\n### 4. Commands (Control Phase)\n\n#### 4.1. `CommandEnumerate` (`0x01`)\n\n- **Purpose:** Requests a list of available FIDO2 HID devices.\n- **Client Request:**\n  - Command: `0x01`\n  - Length: `0x0000` (0)\n  - Data: (empty)\n  \n- **Server Response (Success):**\n  - Command: `0x01`\n  - Length: Size of the CBOR-encoded device list.\n  - Data: A CBOR-encoded array of `DeviceInfo` objects. Each `DeviceInfo` object contains details about a discovered\n    FIDO2 HID device, typically including fields like:\n    - `Path`: A system-specific path to the device (e.g., `\\\\?\\hid#vid_xxxx\u0026pid_yyyy...`). **This path is crucial for\n      the `CommandStart` request.**\n    - `VendorID`: USB Vendor ID.\n    - `ProductID`: USB Product ID.\n    - `ManufacturerString`: Manufacturer name.\n    - `ProductString`: Product name.\n    - (Other fields as provided by the underlying `go-hid` library for FIDO2 devices, specifically those with\n      `UsagePage == 0xf1d0` and `Usage == 0x01`).\n- **Server Response (Error):**\n  - If an error occurs during enumeration (e.g., HID subsystem error), the server might close the connection or send an\n    error response (the current code implies connection closure or no specific error message format for this command).\n\n#### 4.2. `CommandStart` (Value: `0x02`)\n\n- **Purpose:** Instructs the proxy to start relaying raw CTAPHID packets for a specific FIDO2 HID device.\n  After a successful `CommandStart`, the protocol transitions to the [Proxy Phase](#5-proxy-phase-after-successful-commandstart).\n- **Client Request:**\n  - Command: `0x02`\n  - Length: Size of the CBOR-encoded device path string.\n  - Data: A CBOR-encoded string containing the `Path` of the FIDO2 HID device to connect to. This path should be one of\n    the paths obtained from a previous `CommandEnumerate` response.\n- **Server Response / Behavior:**\n  - **Success:**\n    - The server attempts to open the specified HID device.\n    - If successful, the server **does not send a structured `Message` response**.\n    - Instead, the named pipe connection transitions into the [Proxy Phase](#5-proxy-phase-after-successful-commandstart).\n      The pipe remains open, and subsequent data sent by the client will be treated as raw CTAPHID packets destined\n      for the HID device.\n  - **Failure:**\n    - If the server fails to open the specified HID device (e.g., device not found, access denied at the HID level),\n      the proxy service will typically close the named pipe connection. The client will detect this as an EOF or\n      connection error.\n    - If another proxy session is already active for the same device path, the proxy service closes the new named pipe\n      connection.\n\n### 5. Proxy Phase (After successful `CommandStart`)\n\nOnce `CommandStart` is successfully processed:\n\n- **Client to Server (to HID Device):**\n  - The client writes raw CTAPHID request reports directly to the named pipe. These reports should include the HID\n    report ID byte followed by the 64-byte CTAPHID packet. The `go-ctaphid` library handles this formatting.\n  - The proxy service reads complete 65-byte HID reports from the pipe and writes them directly to the selected HID\n    device.\n- **Server (from HID Device) to Client:**\n  - The proxy service reads raw CTAPHID response packets from the HID device.\n  - These packets are written directly to the named pipe for the client to read.\n\n**Data Flow in Proxy Phase:**\n\n```\nClient App  \u003c--Raw CTAPHID Packets--\u003e Named Pipe \u003c--\u003e Proxy Service \u003c--\u003e HID Device\n```\n\n**Termination:**\nThe proxy session for a given device ends when:\n*   The client closes its end of the named pipe.\n*   An error occurs during communication with the HID device, causing the proxy to close the connection.\n*   The HID device is disconnected.\n\nIn these cases, the named pipe connection will be closed. To communicate with another device or retry,\nthe client must establish a new connection and restart the protocol from the Control Phase.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-ctap%2Fwindows-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-ctap%2Fwindows-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-ctap%2Fwindows-proxy/lists"}