https://github.com/go-ctap/kit
Complete application runtime to integrate FIDO2 hardware token management into your app
https://github.com/go-ctap/kit
authentication authorization ctap2 ctaphid fido2 hardware-token hid runtime sdk sdk-go
Last synced: about 20 hours ago
JSON representation
Complete application runtime to integrate FIDO2 hardware token management into your app
- Host: GitHub
- URL: https://github.com/go-ctap/kit
- Owner: go-ctap
- License: other
- Created: 2026-05-03T18:38:50.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-05-20T00:05:56.000Z (24 days ago)
- Last Synced: 2026-05-20T03:07:53.146Z (24 days ago)
- Topics: authentication, authorization, ctap2, ctaphid, fido2, hardware-token, hid, runtime, sdk, sdk-go
- Language: Go
- Homepage:
- Size: 196 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# ctapkit
Reusable CTAP/FIDO2 runtime core for the `go-ctap` application family.
The current Go module is:
```go
module github.com/go-ctap/kit
```
The root package is imported as:
```go
import "github.com/go-ctap/kit"
import "github.com/go-ctap/kit/model"
import "github.com/go-ctap/kit/transport"
```
## What This Is
`ctapkit` provides the shared runtime boundary for applications that need to discover, inspect, and safely control local FIDO2 authenticators. It is designed for CLI, GUI, and TUI consumers that want the same device/session/operation semantics without duplicating CTAP safety logic.
This repository does not own terminal UX, command parsing, output rendering, MDS presentation, release packaging, or product-specific workflows. Those live in consumer applications.
## Package Layout
- `ctapkit`: public runtime facade.
- `model`: public operation, event, interaction, and session DTOs.
- `model/config`: authenticator config DTOs and reports.
- `model/credentials`: credential DTOs, previews, and reports.
- `model/largeblobs`: large-blob DTOs, previews, and reports.
- `model/report`: shared report DTOs used across model domains.
- `model/safety`: shared safety/confirmation DTOs.
- `transport`: HID and Windows proxy transport boundary.
- `internal/device`: device discovery, selection identity, and leases.
- `internal/runtime`: event, interaction, and token policies.
- `internal/session`: opened-session core, lifecycle, serialization, and cache boundary.
- `internal/workflow`: operation dispatch and domain workflow bodies over an explicit execution environment.
## Session Flow
A consumer should generally do this:
1. Convert UI or CLI input into a typed `model.Operation`.
2. Discover devices with `ctapkit.DiscoverDevices`.
3. Pick one returned `ctapkit.Device` handle and open it with `ctapkit.OpenSession`.
4. Run one typed operation synchronously with `Session.Run`.
5. Clean up with `Session.Close`.
`Session.Run` returns the typed `model.OperationResult` directly. Consumers that need non-blocking UI can call it from their own goroutine or task. Progress and UI updates are delivered through the `model.EventSink` attached with `ctapkit.WithEventSink`; PIN, user-verification, touch, and confirm participation is delivered through `model.InteractionHandler`.
Interaction requests and operation events contain only their prompt or event payload; consumers should correlate session-specific work through the `*ctapkit.Session` handle and their own event sink ownership.
Verification defaults to UV when the authenticator supports it, with PIN fallback when CTAP reports a fallback condition. A consumer that wants to offer "use PIN" before starting work can pass `ctapkit.WithVerificationFlow(model.VerificationFlowPIN)` to `Session.Run`. User-verification interactions are pre-command prompt and cancel points; the authenticator remains authoritative for whether UV actually succeeds.
Core operations are intentionally UI-neutral. PIN prompts, user verification messages, spinners, progress bars, tables, JSON/YAML formatting, and GUI/TUI event presentation belong to the consumer.
MDS lookup is exposed as a root facade helper rather than a session operation:
```go
metadata, err := ctapkit.LookupMDS(ctx, inspect.Result.Info.AAGUID)
```
The runtime fetches and verifies the FIDO MDS3 blob, indexes entries by AAGUID,
and caches the verified response in memory and on disk under the user cache
directory. Disk cache entries are verified again before use. Consumers own any
MDS presentation or policy decisions.
## Safety Model
- Per-session workflow serialization prevents multi-step flows on the same opened authenticator from interleaving.
- Device leases represent cross-session or cross-process ownership of authenticator identity; different authenticators may run independently.
- Secrets such as PIN input and `pinUvAuthToken` must not be logged, marshaled, or exposed through public results.
- Mutating operations preserve dry-run and confirmation semantics.
- Destructive flows such as reset, credential deletion, and large-blob deletion require explicit confirmation.
- Factory reset must be executed shortly after authenticator power-up on many authenticators; consumers should collect any strong UI confirmation before reconnecting and then run a confirmed reset promptly.
## Verification
Run the default checks with:
```powershell
go test ./... -count=1
go vet ./...
```
For lifecycle, session, interaction, or synchronization changes, also run:
```powershell
go test -race ./... -count=1
```